commonsensesoftware
commented
9 months ago Nice! Glad to see you moving to the new. The migration is a little rough, even with just plain 'ol OData, but the end result is largely better.
Issue 1
I don't have any control or influence over what the OData team does with routing. I just follow the leader. I can say that OData 8.0+ is more inline with intrinsic ASP.NET Core routing, which means you have less to learn about the OData way to do things. There's still gotchas and you have to know the OData URL conventions, but it's better. For API Versioning, this meant significantly less forking, hacking, and conversion of OData routing mechanics. I can lean in a lot more on what OData provides, especially for URL generation, which is nice.
Issue 2
When you say casing, I presume you are referring to the casing of JSON returned. I had to spelunk the commits, but this was changed over 5 years ago. Comparing dates, it looks like this has been the behavior for OData on ASP.NET Core since API Versioning 3.0.0-beta1, which was the first version to support OData. If you had been using OData on legacy ASP.NET Web API, Pascal/Title case that was the default up until 2.2.0. This change was made because the majority of users expect JSON to be Camelcase in alignment with JSON standards. Furthermore, that is the default in ASP.NET Core itself now (for years), even without OData. The goal was to have congruency and one less knob to turn.
Fear not! You can easily go back to Pascalcase if you want it.
var builder = WebApplication.CreateBuilder( args );
builder.Services.AddControllers().AddOData(); // ← this adds OData services
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning()
.AddOData( // ← this adds OData to API Versioning
options =>
{
// the default setup uses:
// new ODataConventionModelBuilder().EnableLowerCamelCase()
options.ModelBuilder.ModelBuilderFactory = static () => new ODataConventionModelBuilder();
// route components have to be add here (sadly 😢) because there is no way to extend,
// customize, or otherwise get in front of the OData configuration. every effort was made
// to make things look and feel like the native OData API and configuration
options.AddRouteComponents( "api" );
} );Issue 3
The OData spec itself has continued to evolve. The $ prefix is no longer required. There's a long history that some implementers didn't like the $ prefix, which hindered adoption (like Azure). The original intend was for these query parameters to be unambiguously specific to OData. The OData spec now allows all System Operators to not require a $ prefix, which makes them look more like any other query parameter or REST API.
OData 8.0 established parity with this capability back in the first 8.0 release candidate circa 2/2021. The default configuration is to not include the $, but you can add it back:
var builder = WebApplication.CreateBuilder( args );
// OData query options and route options are shared across all versioned routes so you only need
// to define them once for your application. Route components (e.g. AddRouteComponents) MUST
// be done through the API Versioning extensions not the native OData methods. such routes are
// ignored by API Versioning if you do.
//
// Re-enable the $ prefix
builder.Services.AddControllers().AddOData(options = options.EnableNoDollarQueryOptions = false);
builder.Services.AddProblemDetails();
builder.Services.AddApiVersioning().AddOData();Issue 4
I'm not 100% sure on this one. Is this in reference to defining a parameter as optional in an EDM function or in the OpenAPI documentation? I'd have to refer back to the specs and documentation. OData has little-to-no OpenAPI support and it produces a lot less than the API Explorer extensions that API Versioning provides. My best guess is that there is either a mismatch or the route template isn't correct (which I've been snagged by many times).
I took a few of the existing functions and just added optional query parameters. It seemed to work just fine. I did not include the parameter in the EDM. I'm not sure if that is a requirement.
/// <summary>
/// Gets the sales tax for a postal code.
/// </summary>
/// <param name="postalCode">The postal code to get the sales tax for.</param>
/// <param name="extra">Something extra.</param>
/// <returns>The sales tax rate for the postal code.</returns>
[HttpGet( "api/GetSalesTaxRate(PostalCode={postalCode})" )]
[ProducesResponseType( typeof( double ), Status200OK )]
public IActionResult GetSalesTaxRate( int postalCode, string extra = null ) => Ok( 5.6 );/// <summary>
/// Gets the new hires since the specified date.
/// </summary>
/// <param name="since">The date and time since people were hired.</param>
/// <param name="options">The current OData query options.</param>
/// <param name="extra">This is extra.</param>
/// <returns>The matching new hires.</returns>
/// <response code="200">The people were successfully retrieved.</response>
[HttpGet( "api/People/NewHires(Since={since})" )]
[Produces( "application/json" )]
[ProducesResponseType( typeof( ODataValue<IEnumerable<Person>> ), Status200OK )]
public IActionResult NewHires(
DateTime since,
ODataQueryOptions<Person> options,
string extra = null ) => Get( options );
cfauchere
Preethi-Angel
Our projects are currently on OData 7. We are also trying to move from Net7 to Net8. However when doing so we hit a stackoverflow issue that is preventing us from just bumping to Net8 (though we have a hack to workaround). It motivated me enough to try to move to the new stuff instead of keeping the legacy on life support. eg I am trying to move from mvc to endpoint routing and Odata 8 + asp.versioning packages. Doing so I ran into new issues:
packages
Samples
odata/$metadata
before
now
Swagger
before
now