Generally, resources can have multiple presentations, mostly because there may be multiple different clients expecting different representations. Asking for a suitable presentation by a client, is referred 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
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 agent or client side, its called agent-driven content negotiation.
Practically, you will NOT find much usage of server side negotiations because in that way, you have to make lots of assumptions about client expectations. Few things like client context or how client will use the resource representation is almost impossible to determine. Apart from that this approach makes the server side code complex, unnecessarily.
So, most REST API implementations rely on agent driven content negotiations. Agent driven content negotiation rely on usage of HTTP request headers or resource URI patterns.
Content negotiation 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”.
Content-Type: application/json
Similarly, to determine what type of representation is desired at client side, HTTP header ACCEPT is used. It will have one of the values as mentioned for Content-Type above.
Accept: application/json
Generally, if no Accept header is present in the request, the server can send pre-configured default representation type.
Implementing Accept header based content negotiation is most used and recommened way.
Content negotiation using URL patterns
Another way to pass content type information to server, client may use specific extension in resource URIs. For example, a client can ask for details using:
http://rest.api.com/v1/employees/20423.xml
http://rest.api.com/v1/employees/20423.json
In above case, first request URI will return a XML response whether second request URI will return a JSON response.
Defining preferences
If is possible to have multiple values in Accept header. Client may want to give multiple values in accept header when client is not sure about if its desired representation is present or supported by server at that time. [RFC 2296]
For example,
Accept: application/json,application/xml;q=0.9,*/*;q=0.8
Above Accept header allows you to ask the server a JSON format. If it can’t, perhaps it could return XML format (the second level). 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 value is 1.
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
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 agent or client side, its called agent-driven content negotiation.
Practically, you will NOT find much usage of server side negotiations because in that way, you have to make lots of assumptions about client expectations. Few things like client context or how client will use the resource representation is almost impossible to determine. Apart from that this approach makes the server side code complex, unnecessarily.
So, most REST API implementations rely on agent driven content negotiations. Agent driven content negotiation rely on usage of HTTP request headers or resource URI patterns.
Content negotiation 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”.
Content-Type: application/json
Similarly, to determine what type of representation is desired at client side, HTTP header ACCEPT is used. It will have one of the values as mentioned for Content-Type above.
Accept: application/json
Generally, if no Accept header is present in the request, the server can send pre-configured default representation type.
Implementing Accept header based content negotiation is most used and recommened way.
Content negotiation using URL patterns
Another way to pass content type information to server, client may use specific extension in resource URIs. For example, a client can ask for details using:
http://rest.api.com/v1/employees/20423.xml
http://rest.api.com/v1/employees/20423.json
In above case, first request URI will return a XML response whether second request URI will return a JSON response.
Defining preferences
If is possible to have multiple values in Accept header. Client may want to give multiple values in accept header when client is not sure about if its desired representation is present or supported by server at that time. [RFC 2296]
For example,
Accept: application/json,application/xml;q=0.9,*/*;q=0.8
Above Accept header allows you to ask the server a JSON format. If it can’t, perhaps it could return XML format (the second level). 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 value is 1.
No comments:
Post a Comment