1. Content Negotiation
Generally, the REST resources can have multiple presentations, mostly because there may be different clients expecting different representations. Asking for a suitable presentation by a client is referred to as content negotiation.
HTTP has provisions for several mechanisms for “content negotiation” — the process of selecting the best representation for a given response when there are multiple representations available.— RFC 2616
2. Server-driven Vs Agent-driven Content Negotiation
If the selection of the best representation for a response is made by an algorithm located at the server, it is called server-driven negotiation. If that selection is made at the agent or client-side, it is called agent-driven negotiation.
Practically, we will NOT find much usage of server-side negotiations because, in that way, we have to make a lot of assumptions about the client’s expectations.
Few things, like the client context or how the client will use the resource representation, are almost impossible to determine. Also, the server-driven negotiation makes the server-side code more complex, unnecessarily.
So, most REST API implementations rely on agent-driven content negotiations. Agent-driven content negotiation depends on the usage of HTTP request headers or resource URI patterns.
2.1. Using HTTP Headers
At server side, an incoming request may have an entity attached to it. To determine it’s type, server uses the HTTP request header
Content-Type. Some common examples of content types are “text/plain”, “application/xml”, “text/html”, “application/json”, “image/gif”, and “image/jpeg”.
Similarly, to determine what type of representation is desired on the client-side, an HTTP header ACCEPT is used. It will have one of the values mentioned for
Generally, if no
Accept header is present in the request, the server can send pre-configured default representation type.
Acceptheader based content negotiation is most used and recommened way.
2.2. Using URL Patterns
Another way to pass content type information to the server, the client may use the specific extension in resource URIs. For example, a client can ask for details using:
In the above case, the first request URI will return an XML response whether the second request URI will return a JSON response.
3. Defining Preferences
It is possible to have multiple values in
Accept header using the ‘q’ parameter i.e. relative quality factor.
The client may want to provide multiple values in the accept header when the client is not sure if its desired representation is present or supported by the server at that time. [RFC 2296]
Accept header allows you to ask the server a JSON format (first choice). If it can’t, perhaps it could return XML format (the second choice). If it’s still not possible, let it return what it can.
The preference order is defined through the q parameter with values from 0 to 1. When nothing is specified, the implicit default value is 1.