REST API - Content Negotiation

Please find part 1 of this series in the above link.

Generally, REST resources can have multiple representations of the data. Different clients may expect different representations.

Asking for a specific format of the resource via the REST URL is called content negotiation.

The process of selecting the best representation for a given response when there are multiple representations available is called Content Negotiation.

This identification and negotiation can be done in two ways:

1. Using specific HTTP headers - Server-driven content negotiation or proactive negotiation
2. Selecting a compatible resource from the list of available resources - (agent-driven negotiation?or?reactive negotiation)

Server-driven Content Negotiation

This is achieved by sending several HTTP headers with the URL with which the server can format the response. If it can't provide a suitable resource, it might respond with?406?(Not Acceptable) or?415?(Unsupported Media Type) and /or set headers for the types of media that it does support (using the?Accept-Post for POST and?Accept-Patch?for PATCH requests).

The different HTTP headers available are:

1. Accept: Used to tell the server what media types can be sent
2. Accept-Language: Used to tell the server what languages can be sent
3. Accept-Charset: Used to tell the server what charsets can be sent
4. Accept-Encoding: Used to tell the server what encodings can be sent

Although flexible, server-driven content negotiation has a few drawbacks. It does not scale well. Sending every request with precise headers/custom headers to get the appropriate response from the server may cause an increase in the message size. This could affect the performance of the server.

Agent-driven Content Negotiation

To allow the client to choose from the list of resources available on the server, agent-driven content negotiation was built.

But, this will need multiple requests to get the appropriate response from the server; the server will return the list of resources with a 300 header, from which the client then chooses the actual resource from the list.

Since there is no specific HTTP format on how to select the required format from the available list of resources, this process cannot be automated. Two requests to get the resource really slow down the system. And the second request, to actually request the specific format, falls back to server-driven content negotiation, which prevents developers from using this type of content negotiation.

Implementation of server-driven content negotiation is made easy by Spring Boot's starter:

<dependency
			<groupId>com.fasterxml.jackson.dataformat</groupId>
			<artifactId>jackson-dataformat-xml</artifactId>
			<version>2.15.0-rc3</version>
</dependency>        

Based on the Accept header, Jackson will perform the required data formatting.

With value application/json

With value application/xml

References:

1. https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation
2. https://www.holisticseo.digital/technical-seo/http-header/content-negotiation/