Content negotiation is one of those quality-of-life improvements you can add to your REST API to make it more user-friendly and flexible. And when we design an API, isn’t that what we want to achieve in the first place?
There are many things to keep in mind when designing a REST API and we’ve written recently about it in our Top REST API best practices article. Content negotiation is an HTTP feature which has been around for a while, but for one reason or another, it is, maybe, a bit underused.
In short, content negotiation lets you choose or rather “negotiate” the content you want in to get in response to the REST API request. If you want to learn how content negotiation works behind the scenes, you can download our Complete Guide to HTTP Book for free and look it up in the advanced features section.
Today, we are going through the content negotiation implementation in ASP.NET Core.
We are going to talk about:
- What You Get out of the Box With ASP.NET Core 2.0
- How to Use Postman to Test Your API
- Changing the Default Configuration of Our Project
- Testing Content Negotiation
- Restricting Media Types
- More About Formatters
- Implementing a Custom Formatter
- A Note About .NET Core 2.2
- Consuming API Programmatically
So let’s get down to it.
What DO You Get out of the Box?
By default, ASP.NET Core Web API returns a JSON formatted result.
Let’s make a default Web API project and remove the default ValuesController. Instead, we are going to make our own controller (with blackjack and hookers), BlogController with only one method:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
[Route("api/[controller]")] public class BlogController : Controller { public IActionResult Get() { var blogs = new List<Blog>(); var blogPosts = new List<BlogPost>(); blogPosts.Add(new BlogPost { Title = "Content negotiation in .NET Core", MetaDescription = "Content negotiation is one of those quality-of-life improvements you can add to your REST API to make it more user-friendly and flexible. And when we design the API, isn't that what we want to achieve in the first place?", Published = true }); blogs.Add(new Blog() { Name = "Code Maze", Description = "A practical programmers resource", BlogPosts = blogPosts }); return Ok(blogs); } } |
Things to note about this simple example:
- We are using two classes: Blog and BlogPosts to create an object to return as a response object
- We are utilizing the IActionResult interface provided by ASP.NET Core as a generic return type for different types of responses our methods might have
- The object creation logic is in the controller. You should not implement your controllers like this; this is just for the sake of simplicity
- We are returning the result with the Ok helper method which returns the object and the status code
200 OK
How to Use Postman to Test Your API
Postman is a nice little tool you can use to test your APIs easily. Now, let’s try calling the method using Postman and see what we get as a response.
You can clearly see that the default result when calling GET on /api/blog returns our JSON result. Those of you with sharp eyes might have even noticed that we used the Accept header to try forcing the server to return other media types like plain text and XML.
But that doesn’t work. Why?
Because we need to configure server formatters to format a response the way we want it.
Let’s see how to do that.
Changing the Default Configuration of Our Project
A server does not explicitly specify where it formats a response to JSON. But you can override it by changing configuration options through the AddMvc method options. By default, it looks like this:
|
1 2 3 4 |
public void ConfigureServices(IServiceCollection services) { services.AddMvc(); } |
We can add the following options to enable the server to format the XML response when the client tries negotiating for it.
|
1 2 3 4 5 6 7 8 9 10 |
public void ConfigureServices(IServiceCollection services) { services.AddMvc(config => { // Add XML Content Negotiation config.RespectBrowserAcceptHeader = true; config.InputFormatters.Add(new XmlSerializerInputFormatter()); config.OutputFormatters.Add(new XmlSerializerOutputFormatter()); }); } |
First things first, we must tell a server to respect the Accept header. After that, we can add XML formatters to enable the XML formatting. XmlSerializerInputFormatter and XmlSerializerOutputFormatter are both part of the Microsoft.AspNetCore.Mvc.Formatters, so we need to add a reference to that library.
Now that we have our server configured let’s test the content negotiation once more.
Testing Content Negotiation
Let’s see what happens now if we fire the same request through Postman.
There is our XML response.
That was easy, wasn’t it?
Now by changing the Accept header from text/xml to text/json, we can get differently formatted responses which is awesome, wouldn’t you agree?
Ok, that was nice and easy.
But what if despite all this flexibility a client requests a media type that a server doesn’t know how to format?
Restricting Media Types
Currently, it will default to a JSON type.
But you can restrict this behavior by adding one line to the configuration.
|
1 2 3 4 5 6 7 8 9 10 11 |
public void ConfigureServices(IServiceCollection services) { services.AddMvc(config => { config.RespectBrowserAcceptHeader = true; config.ReturnHttpNotAcceptable = true; config.InputFormatters.Add(new XmlSerializerInputFormatter()); config.OutputFormatters.Add(new XmlSerializerOutputFormatter()); }); } |
We added the ReturnHttpNotAcceptable = true option, which tells the server that if the client tries to negotiate for the media type the server doesn’t support, it should return the 406 Not Acceptable status code.
This will make your application more restrictive and force the API consumer to request only the types the server supports. The 406 status code is created for this purpose. You can find more details about that in our Complete Guide to HTTP book, or if you want to go even deeper you can check out the RFC2616.
Now, let’s try fetching the text/css media type using Postman to see what happens.
And as expected, there is no response body, and all we get is a nice 406 Not Acceptable status code.
So far so good.
More About Formatters
Let’s imagine you are making a public REST API and it needs to support content negotiation for a type that is not “in the box”. Rare as it might occur, you need to have a mechanism to do this.
So, how can you do that?
ASP.NET Core supports the creation of custom formatters. Their purpose is to give you the flexibility to create your own formatter for any media types you need to support.
We can make the custom formatter using the following method:
- Create an output formatter class that inherits the
TextOutputFormatterclass - Create an input formatter class that inherits the
TextInputformatterclass - Add input and output classes to
InputFormattersandOutputFormatterscollections the same way as we did for the XML formatter
Now let’s have some fun and implement a custom CSV formatter for our example.
Implementing a Custom Formatter
Since we are only interested in formatting responses in this article, we need to implement only an output formatter. We would need an input formatter only if a request body contained a corresponding type.
The idea is to format a response to return the list of blogs and their corresponding list of blog posts in a CSV format.
Let’s add a CsvOutputFormatter class to our project.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
public class CsvOutputFormatter : TextOutputFormatter { public CsvOutputFormatter() { SupportedMediaTypes.Add(MediaTypeHeaderValue.Parse("text/csv")); SupportedEncodings.Add(Encoding.UTF8); SupportedEncodings.Add(Encoding.Unicode); } protected override bool CanWriteType(Type type) { if (typeof(Blog).IsAssignableFrom(type) || typeof(IEnumerable<Blog>).IsAssignableFrom(type)) { return base.CanWriteType(type); } return false; } public override Task WriteResponseBodyAsync(OutputFormatterWriteContext context, Encoding selectedEncoding) { var response = context.HttpContext.Response; var buffer = new StringBuilder(); if (context.Object is IEnumerable<Blog>) { foreach (var Blog in (IEnumerable<Blog>)context.Object) { FormatCsv(buffer, Blog); } } else { FormatCsv(buffer, (Blog)context.Object); } using (var writer = context.WriterFactory(response.Body, selectedEncoding)) { return writer.WriteAsync(buffer.ToString()); } } private static void FormatCsv(StringBuilder buffer, Blog blog) { foreach (var blogPost in blog.BlogPosts) { buffer.AppendLine($"{blog.Name},\"{blog.Description},\"{blogPost.Title},\"{blogPost.Published}\""); } } } |
There are a few things to note here:
- In the constructor, we define which media type this formatter should parse as well as encodings
- The
CanWriteTypemethod is overridden, and it indicates whether or not theBlogtype can be written by this serializer. - The
WriteResponseBodyAsyncmethod that constructs the response - And finally, we have the
FormatCsvmethod that formats a response the way we want it.
The class is pretty straightforward to implement, and the main thing that you should focus on is the FormatCsv method logic.
Now, we just need to add the newly made formatter to the list of OutputFormatters in the AddMvcOptions.
|
1 2 3 4 5 6 7 8 9 10 11 12 |
public void ConfigureServices(IServiceCollection services) { services.AddMvc(config => { config.RespectBrowserAcceptHeader = true; config.ReturnHttpNotAcceptable = true; config.InputFormatters.Add(new XmlSerializerInputFormatter()); config.OutputFormatters.Add(new XmlSerializerOutputFormatter()); config.OutputFormatters.Add(new CsvOutputFormatter()); }); } |
Now let’s run this and see if it actually works. This time we will put the text/csv as the value for the Accept header.
Well, what do you know, it works!
Since we only have one blog and one blog post in our example, there is only one line in the response.
You can play around with source code to see what happens when you add more blogs and blog posts.
There is a great page about custom formatters in ASP.NET Core if you want to learn more about them. You can also check out the implementation of the input and output formatters for the vcard content type if you need more examples.
A Note About .NET Core 2.2
If you are using .NET Core 2.2 or latest XmlSerializerInputFormatter should be marked as deprecated.
A better way would be to implement XML serializers like this:
|
1 2 3 4 5 6 7 8 9 10 |
public void ConfigureServices(IServiceCollection services) { services.AddMvc(config => { config.RespectBrowserAcceptHeader = true; config.ReturnHttpNotAcceptable = true; config.OutputFormatters.Add(new CsvOutputFormatter()); }).AddXmlSerializerFormatters().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); } |
Instead of explicitly defining XML serializers as we did before, in the .NET Core 2.2 we can add them simply by calling AddXmlSerializerFormatters() method which will do the job now.
This is the preferred way of defining XML serializers since .NET Core 2.2 because otherwise, we could get serialization problems in some cases. You can read more on this issue if you want to see what the potential consequences are (besides deprecation in future versions of .NET Core).
Modified source code for the .NET Core 2.2 can be found on the Content Negotiation examples 2.2 branch on GitHub.
Consuming API Programmatically
Up until now, we have used Postman to play around with the example. But, I feel you need to try out to consume some REST APIs using content negotiation we described here by making some requests programmatically instead of using the third party tool.
For that purpose, we have laid out a few great ways to consume RESTful API. You can find some of the best tools that .NET provides to consume any REST API. Be sure to check it out and try consuming some APIs.
Conclusion
In this blog post, we went through a concrete implementation of the content negotiation mechanism in an ASP.NET Core project. We have learned about formatters and how to make a custom one, and how to set them up in your project configuration as well.
We have also learned how to restrict an application only to certain content types, and not accept any others.
You should be able both to design and consume REST APIs using content negotiation now. It really is a great mechanism, and we have great tools to implement it in our projects, easily. So, there are no excuses!
If you want to play around with the source code, you can find it here: Download source code from GitHub.
Thanks for reading and please leave a comment in the comment section.
If you have enjoyed reading this article and if you would like to receive the notifications about the freshly published .NET Core content we encourage you to subscribe to our blog.
Thank you
Hey Richard, glad it helped!
In AspNetCore 2.2, if you manually add the XmlFormatters to the config like you have, then it fails to correctly serialize errors, but if you add them by calling AddXmlSerializerFormatters on the IMvcBuilder, then it all works. Like:
services.AddMvc(config=>{ ... stuff here ...}).AddXmlSerializerFormatters().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);Hi Robert, great information, thanks!
Do you have an example or a blog post that shows off this behavior?