Content negotiation is an important part of REST API. It makes it possible to reveal a resource in various formats and allow the client choose which is best. A client can ask for the resource in a specific format using the Accept header. With this, the server serve the request to match the specific format and if the format is not supported, it returns a 406 Not Acceptable.
We saw examples in this article(Building a Simple Web API) that all the responses are JSON, but we can also get XML format too.
Consider the Student example, add Accept header with “text/xml”, and build a request like this:
This means that the client want to get all the Students in XML format. In fact, the server responds with an XML response:
This works because the ASP.NET Web API has the XmlFormatter included in the list of available formatters. Formatters are objects that inherit from MediaTypeFormatter which is an abstract class.
In the ASP.NET Web API,already there are four media type formatters out-of-the-box:
- JsonMediaTypeFormatter: Format the requested resource in JSON format (this is the default formatter).
- XmlMediaTypeFormatter: Format the requested resource in XML format.
- FormUrlEncodedMediaTypeFormatter: This is used to manage the application/x-www-form-urlencoded requests.
- JQueryMvcFormUrlEncodedFormatter: Derives from the FormURLEncodedMediaTypeFormatter and adds support for the JQuerySchema.
Let we modify our Student class and add a field Picture that hold the profile picture of student.
So if we request a single Student, result is:
Now, What we want is the photo of the Student, but we would like to use the same URI we used to obtain the Student info (/api/students/1). So, we create a new GET request with the Accept header that specifies “image/jpg”. As response, we want a JPG image of student with id 1.
To perform this we a new MediaTypeFormatter that takes the Student object from the controller and replaces it with his photo. Implementtation of new formatter is:
To add the ImageFormatter media type formatter to the Web API pipeline, we need to register it by using the Formatters property on the HttpConfiguration object when the application starts:
Now we call the API resource with following parameters
The response we are getting is:
The nice thing is that with the same URI, we have two different representations, and we can decide which one we want using different headers.
I hope that you will have better understanding of Content Negotiation in Web API. I would like to hear valuable feedback or question from you. It encourage me to write more quality article.
Happy Reading 🙂