REST API Design: What Is Content Negotiation?

Content negotiation is a mechanism defined in the HTTP specification that makes it possible to serve
different versions of a document (or more generally, a resource representation) at the same URI,
when a user agent submits a request to a server, the user agent informs the server of what media types it understands with ratings of how well it understands them.

More precisely, the user agent provides an Accept HTTP header that lists acceptable media types and associated quality factors.
The server is then able to supply the version of the resource that best fits the user agent’s needs.

The process of selecting the best representation for a given response when there are multiple representations available

Server-driven negotiation

If the selection of the best representation for a response is made by an algorithm located on the server, it is called server-driven negotiation.

Agent-driven negotiation

With agent-driven negotiation, the selection of the best representation for a response is performed by the user agent after receiving an initial
response from the origin server.

Transparent negotiation

Transparent negotiation is a combination of both server-driven and agent-driven negotiation.

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.
Content-Type header helps in determining the type of the incoming request (e.g. XML, JSON).
Example of the OrderItems in Orders API

Create Order using JSON Request

Content-Type: application/json
POST /orders # Creates a new order

Accept header

Determine what type of representation is required on the client side.
API can specify the data format they accept in the response by using Accept header.

Get orders in JSON format

GET /orders
Accept: application/json