REST resources can have multiple presentations (e.g. JSON or XML) as different clients can request different representation. The mechanism for selecting a correct representation is known as content negotiation. It helps to understand the type of data received by the system and expected response data format by the client.Here is a high level workflow representing the content negotiation:
1. Server Vs Client Driven Content Negotiation
Content negotiation can happen at the server or client side.Below are the high-level details of both approaches.
- In the server-driven negotiation, a server process selects best representation for the response.
- For client-driven content negotiation, the client made the selection for the resource representation.
[pullquote align=”normal”]REST API implementations work based on client-driven content negotiation [/pullquote]
2. Content Negotiation using HTTP Headers
HTTP headers provide following 2 types of information for the negotiation
Content-Type:This header tells about the media type of the body of the request.
Accept header:Determine what type of representation required on the client side.
2.1 Content-Type Header
Content-Type header helps in determining the type of the incoming request (e.g. XML, JSON).This header helps server or the client to select the correct approach to handle and eventually parse the data by selecting right converter. Some known Content-Type headers are
POST /customers HTTP/1.1
There are other content headers that can be used with Content-Type header
Content-Encoding:The header shows what other content encodings applied to the payload.
Content-Language:The header describes the natural language.
[pullquote align=”normal”]Server or client can send 415 status code(Unsupported media type) if they do not support the format sent in the request. [/pullquote]
2.2 The Accept Header
Client or calling API can specify data format they accept in the response by using Accept header.
GET /customers HTTP/1.1
HTTP/1.1 200 OK
Server API use default content mechanism if no Accept header is present in the request.There are other content headers that can be used with Accept header
Accept-Language:List of acceptable languages.
Accept-Encoding:List of acceptable encodings.
Accept-Charset:Acceptable charset list.
[pullquote align=”normal”]If the server cannot send data in a format requested in the Accept header, the server sends the 406 Not Acceptable error. [/pullquote]
3. Content Negotiation using URL Extension
URL extension or suffix is another content negotiation strategy used by multiple systems.Client API can use the extension or suffix in the resource URI to inform expected content type. Let’s take an example to understand this strategy.
- The first request will return XML response while the second request is for the JSON data.
Similar to the Accept header strategy, server API use default content mechanism when the extension is not provided in the URL.
4. Content Negotiation in Spring MVC
We covered content negotiation in REST API. Spring MVC and Spring Boot support both strategies as described above. Spring MVC additionally support parameter based content negotiation. Please read our article Spring MVC Content Negotiation to understand the different strategy provided by Spring MVC.
In this article, we covered content negotiation for a REST API. We discussed two different strategies. In the last section, we covered content negotiation strategies provided by Spring MVC