Introduction to REST Content Negotiation

by

In the previous article of REST with Spring Series, we discussed HTTP Methods in RESTful Web Services.In this post, we will discuss content negotiation for a REST API.

 

Introduction

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:

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

  • application/xml
  • text/plain
  • application/json
Content-Type: application/json
POST /customers HTTP/1.1
Content-Type: application/json

{
  "lastName": "Fielding",
  "firstName": "Roy"
}

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.

Accept: application/json

//complete example
GET /customers HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "firstName": "Umesh",
    "lastName": "Awasthi"
  }
]

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.

http://www.javadevjournal.com/v1/customers/1234.xml
http://www.javadevjournal.com/v1/customers/1234.json
  • 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.

 

Summary

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

Comments are closed.