Content Negotiation
If you are building an API to serve just one client then you could just return a default representation to that client to consume. What if the API has to support multiple clients each having different representation requirements? i.e. Client A wants to consume a JSON representation of a resource, while Client B wants to consume an XML representation of the same resource.
The API should be flexible enough to support different representations. This is where Content Negotiation comes into play.
The formal definition of Content Negotiation is:
the process of selecting the best representation for a given response when there are multiple representations available.
The way Content Negotiation works is that the client passes a media type via the accept header of the request. The media type can be JSON, XML, etc. If the API supports the requested media type, it will return the appropriate representation. If the API does not support the requested media type then a 406 - Not Acceptable status code is returned back to the client.
Let's take a look at an example of how to implement this in ASP.NET Core Web API. We will use the sample Weather Forecast API application made available by Microsoft. This app provides an API that returns a list of randomized weather forecast data.
Currently if we pass in a JSON media type in the accept header of the request, a JSON representation of the resource is returned back to the client. This is what we would expect. But what if we pass in an XML media type in the accept header of the request?
The API still returns a JSON representation of the resource. This is not correct. Since the client has asked for an XML response to be returned, the API should return an XML response and not a JSON response. Let's fix this first. If the API does not support the requested media type a 406 - Not Acceptable status code will be returned back to the client. We can do this by setting the ReturnHttpNotAcceptable flag to true.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers(options => {
options.ReturnHttpNotAcceptable = true;
});
var app = builder.Build();
app.UseAuthorization();
app.MapControllers();
app.Run();If we now pass in an XML media type in the accept header of the request, the API returns a 406 - Not Acceptable status code since it doesn't support representations in XML.
What if there was a requirement to support XML representations though?
This is relatively easy to do. We can just add the XMLSerializerFormatter.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers(options =>
{
options.ReturnHttpNotAcceptable = true;
}).AddXmlSerializerFormatters();
var app = builder.Build();
app.UseAuthorization();
app.MapControllers();
app.Run();If we now pass in an XML media type in the accept header of the request, the API returns an XML representation of the resource.
