Enabling Endpoint Routing in OData
Few months ago we announced an experimental release of OData for ASP.NET Core 3.1, and for those who could move forward with their applications without leveraging endpoint routing, the release was considered final, although not ideal.
But for those who have existing APIs or were planning to develop new APIs leveraging endpoint routing, the OData 7.3.0 release didn’t quiet meet their expectations without having to disable endpoint routing.
Understandably this was quite a trade off between leveraging the capabilities of endpoints routing versus being able to use OData. Therefore in the past couple of months the OData team in coordination with ASP.NET team have worked together to achieve the desired compatibility between OData and Endpoint Routing to work seamlessly and offer the best capabilities of both worlds to our libraries consumers.
Today, we announce that this effort is over! OData release of 7.4.0 now allows using Endpoint Routing, which brings in a whole new spectrum of capabilities to take your APIs to the next level with the least amount of effort possible.
Getting Started
To fully bring this into action, we are going to follow the Entity Data Model (EDM) approach, which we have explored previously by disabling Endpoint Routing, so let’s get started.
We are going to create an ASP.NET Core Application from scratch as follows:
Since the API template we are going to select already comes with an endpoint to return a list of weather forecasts, let’s name our project WeatherAPI, with ASP.NET Core 3.1 as a project configuration as follows:
Installing OData 7.4.0 (Beta)
Now that we have created a new project, let’s go ahead and install the latest release of OData with version 7.4.0 by either using PowerShell command as follows:
Install-Package Microsoft.AspNetCore.OData -Version 7.4.0-beta
You can also navigate to the Nuget Package Manager as follows:
Startup Setup
Now that we have the latest version of OData installed, and an existing controller for weather forecasts, let’s go ahead and setup our startup.cs file as follows:
using System.Linq;
using Microsoft.AspNet.OData.Builder;
using Microsoft.AspNet.OData.Extensions;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.OData.Edm;
namespace WeatherAPI
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers();
services.AddOData();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.Select().Filter().OrderBy().Count().MaxTop(10);
endpoints.MapODataRoute("odata", "odata", GetEdmModel());
});
}
private IEdmModel GetEdmModel()
{
var odataBuilder = new ODataConventionModelBuilder();
odataBuilder.EntitySet<WeatherForecast>("WeatherForecast");
return odataBuilder.GetEdmModel();
}
}
}
As you can see in the code above, we didn’t have to disable EndpointRouting as we used to do in the past in the ConfigureServices method, you will also notice in the Configure method has all OData configurations as usual referencing creating an entity data model with whatever prefix we choose, in our case here we set it to odata but you can change that to virtually anything you want, including api.
Weather Forecast Model
Before you run your API, you will need to do a slight change to the demo WeatherForecast model that comes in with the API template, which is adding a key to it, otherwise OData wouldn’t know how to operate on a keyless model, so we are going to add an Id of type GUID to the model, and this is how the WeatherForecast model would look like:
public class WeatherForecast
{
public Guid Id { get; set; }
public DateTime Date { get; set; }
public int TemperatureC { get; set; }
public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
public string Summary { get; set; }
}
Weather Forecast Controller
We had to enable OData querying on the weather forecast endpoint while removing all the other unnecessary annotations, this is how our controller looks like:
using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNet.OData;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
namespace WeatherAPI.Controllers
{
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
[EnableQuery]
public IEnumerable<WeatherForecast> Get()
{
var rng = new Random();
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Id = Guid.NewGuid(),
Date = DateTime.Now.AddDays(index),
TemperatureC = rng.Next(-20, 55),
Summary = Summaries[rng.Next(Summaries.Length)]
})
.ToArray();
}
}
}
Hit Run
Now that we have everything in place, let’s run our API and hit our OData endpoint with an HTTP GET request as follows:
https://localhost:44344/odata/weatherforecast
The following result should be returned:
{
"@odata.context": "https://localhost:44344/odata/$metadata#WeatherForecast",
"value": [
{
"Id": "66b86d0d-375f-4133-afb4-82b44f7f2e79",
"Date": "2020-03-02T23:07:52.4084956-08:00",
"TemperatureC": 23,
"Summary": "Mild"
},
{
"Id": "d534a764-4fb8-4f49-96c5-8f09987a61d8",
"Date": "2020-03-03T23:07:52.4085408-08:00",
"TemperatureC": 9,
"Summary": "Balmy"
},
{
"Id": "07583c78-b2f5-4119-acdb-50511ac02e8a",
"Date": "2020-03-04T23:07:52.4085416-08:00",
"TemperatureC": -15,
"Summary": "Hot"
},
{
"Id": "05810360-d1fb-4f89-be18-2b8ddc75beff",
"Date": "2020-03-05T23:07:52.4085421-08:00",
"TemperatureC": 9,
"Summary": "Hot"
},
{
"Id": "35b23b1a-4803-4c3e-aebc-ced17807b1e1",
"Date": "2020-03-06T23:07:52.4085426-08:00",
"TemperatureC": 16,
"Summary": "Hot"
}
]
}
You can now try the regular operations of $select, $orderby, $filter, $count and $top on your data and examine the functionality yourself.
Non-Edm Approach
If you decide to go the non-Edm route, you will need to install an additional Nuget package to resolve a Json formatting issue as follows:
First of all install Microsoft.AspNetCore.Mvc.NewtonsoftJson package by running the following PowerShell command:
Install-Package Microsoft.AspNetCore.Mvc.NewtonsoftJson -Version 3.1.2
You can also navigate for the package using Nuget Package manager as we did above.
Secondly, you will need to modify your ConfigureService in your Startup.cs file to enable the Json formatting extension method as follows:
using System.Linq;
using Microsoft.AspNet.OData.Extensions;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
namespace WeatherAPI
{
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.AddControllers().AddNewtonsoftJson();
services.AddOData();
}
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
app.UseHttpsRedirection();
app.UseRouting();
app.UseAuthorization();
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
endpoints.EnableDependencyInjection();
endpoints.Select().Filter().OrderBy().Count().MaxTop(10);
});
}
}
}
Notice that we added AddNewtonsoftJson() to resolve the formatting issue with $select, we have also removed the MapODataRoute(..) and added EnableDependencyInjection() instead.
With that, we have added back the weather forecast controller [ApiController] and [Route] annotations in addition to [HttpGet] as follows:
using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNet.OData;
using Microsoft.AspNetCore.Mvc;
namespace WeatherAPI.Controllers
{
[ApiController]
[Route("api/[controller]")]
public class WeatherForecastController : ControllerBase
{
private static readonly string[] Summaries = new[]
{
"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};
[HttpGet]
[EnableQuery]
public IEnumerable<WeatherForecast> Get()
{
var rng = new Random();
return Enumerable.Range(1, 5).Select(index => new WeatherForecast
{
Id = Guid.NewGuid(),
Date = DateTime.Now.AddDays(index),
TemperatureC = rng.Next(-20, 55),
Summary = Summaries[rng.Next(Summaries.Length)]
})
.ToArray();
}
}
}
Now, run your API and try all the capabilities of OData with your ASP.NET Core 3.1 API including Endpoint Routing.
Final Notes
- The OData team will continue to address all the issues opened on the public github repo based on their priority.
- We are always open to feedback from the community, and we hope to get the community’s support on some of our public repos to keep OData and it’s client libraries running.
- With this current implementation of OData you can now enable Swagger easily on your API without any issues, here’s an example
- You can clone the example we used in this article from this repo here to try it for yourself.
- The final release of OData 7.4.0 library should be released within two weeks from the time this article was published.
Light
Dark
42 comments
Good step towards stability. We are pleased to see the update to use OData feature on WebApi without loosing endpoint routing facility. Many thanks to OData team.
Thank you Hassan and team!
Great write-up! Love the detail!
Great potential in odata for a we api.
But a stable typescript, python and kotlin client generator (like in graphQL, openAPI/Swagger, grpc, were clients in many languages are available exporting model dtos and services to consume) would improve the adoption of odata, for now is what is keeping me back to invest in this technology
Very good news… Thank you!
Hi Hassan, thank you for the information, however, I have a question about final note #3. I had been unable to get my OData endpoints to show in my API’s swagger page targeted at .net core 3.1. This blog gave me hope an issue had been resolved, however, even after updating to the 7.4.0-beta, my issue remains. Getting error message:
No media types found in ‘Microsoft.AspNet.OData.Formatter.ODataOutputFormatter.SupportedMediaTypes’.
I also tried to pull down your repo referenced here and follow the guide in the Microsoft doc link you provided to add a swagger page to it and ended up with the same error. Am I missing something?
Yes, I’m also facing the same issue: {“StatusCode”:500,”Message”:”System.InvalidOperationException: No media types found in ‘Microsoft.AspNet.OData.Formatter.ODataOutputFormatter.SupportedMediaTypes’. Add at least one media type to the list of supported media types.”}
I solved this with by adding a media type header to any calls without one by implementing the options InputFormatter and OutputFormatter code block given in Issue 1177. This workaround was mentioned in 2017 and suggested as recently as October 2019, but with 7.4 there could be a better solution.
Hi Parker, here’s an example of enabling Swagger:
https://github.com/hassanhabib/OData3.1WithSwagger
Thanks Hassan, looks good. I appreciate you providing this example.
Thanks Hassan, I just add a simple WebAPI controller wit one method and swager does not work anymore. Saying it does not find the json.
Hi there!
I followed the code OData3.1WithSwagger and also still facing the same issue “json not found”
“Fetch errorInternal Server Error /swagger/v1/swagger.json”
Then if you navigate to /swagger/v1/swagger.json or make an debugger you will find the specific error:
So its ODataInputFormatter (Input) what is failing now.
What I did following both workarounds (Hasssan + the one from 2017) was checking input and output formatters also:
foreach (var outputFormatter in options.OutputFormatters.OfType().Where(_ => _.SupportedMediaTypes.Count == 0)) { outputFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/odata")); } foreach (var inputFormatter in options.InputFormatters.OfType().Where(_ => _.SupportedMediaTypes.Count == 0)) { inputFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/odata")); }with the string “application/odata”, no more “application/prs.odatatestxx-odata”
And worked ! …
I hope it helps someone… I hate workarounds 🙁
Have a good day
A very good step. thanks.
Good article. also Expand() should be added to: endpoints.Select().Filter().OrderBy().Count().MaxTop(10);
WOW, that’s great stuff, keep it coming!
I want to thank you personally and Microsoft in general for reviving OData back.
If I may ask for more, is my wish for the client app to be revived too. Server OData without a proper client is a great half-side-product.
Thank you for the updated information and examples.
Do you have an example of how to setup Swagger?
Thanks.
Hi Gunnar, here’s an example:
https://github.com/hassanhabib/OData3.1WithSwagger
any example for Swagger without the MapODataRoute?