asp.net-web-api ASP.NET Web API Content Negotiation Content Negotiation in Web API

Example

Understanding the concept

To understand content negotiation in Web API, it is important to understand the term Resource.

On the web, any information that we can access can be referred as HTTP resource. There is a tremendous amount of material to view on the web which has different content type such as html documents, images, video, audio, executable files, spreadsheets etc. We can get any resource by making an http request to the resource uri. The http response for the request, returns the resource and also specifies the content type, which is also known as media type.

In order to access any resource, client can make http request by providing specific resource uri and the http verbs. However, in addition to this, client can also specify the accept-type which is the format of the content the user is looking for. The “accept-type” can be defined in the http request headers as the “accept” header.

The server then checks the “accept” header from the requests and returns the response in the specified format, if available. Please note that the server can only return the response in the requested representation if it is available. If the requested representation is not available then it returns the resource in default representation. That is the reason it is called content negotiation.

---

A practical example

As an example, assume that you are making a request to http://example.com/customer/1 to get the information of customer with the id 1. If you don’t specify the “accept” header in the request, the server will return the default representation of this resource.

Assume that the server can return the customer information in json and xml both. Now, it is on the client to specify the required format of the customer information in the “accept” header in the request. The value of the “accept” header can be “application/json” for json representation, or “text/xml” for xml representation. The server will then return the response as per the requested format.

If the requested format is “text/html” which is not supported by this host (as in this example), then it will simply return the resource in the default format. The http response contains a header “content-type” which tells the client about the format of the resource.

Please note that even in the case when the requested representation of the resource is not available, the default representation of the resource is still returned.

That is why it is referred as content negotiation.

The client negotiates the representation of the response, however, if it is not available then gets the default one.

---

How to configure in Web API

In Web API, content negotiation can be configured in the WebAPIConfig class as

config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new System.Net.Http.Headers.MediaTypeHeaderValue("text/html"));

You can also override the default content negotiation in Web API by implementing IContentNegotiator interface and its Negotiate method, and then setup this in the Web API request pipe line, in the WebAPI.config file as below:

GlobalConfiguration.Configuration.Services.Replace(typeof(IContentNegotiator), new CustomContentNegotiator());

Following is a sample implemantation of Negotiate method.

public class CustomContentNegotiator : DefaultContentNegotiator
    {
        public override ContentNegotiationResult Negotiate(Type type, HttpRequestMessage request, IEnumerable<MediaTypeFormatter> formatters)
        {
            var result = new ContentNegotiationResult(new JsonMediaTypeFormatter(), new MediaTypeHeaderValue("application/json"));
            return result;
        }