The resources in the RESTful APIs need to deal with different type of representations—not just XML or JavaScript Object Notation (JSON), as different clients may need different representations. In fact, as we build our complex APIS, we may find that XML/JSON is too limiting, and we may need to move to another type of content in an entirely different format (Instagram and Flickr use JPEG and PNG images, while media houses use MP3/MP4), and that's how we get to content negotiation.

Content-negotiation is a mechanism or process that services and clients can select as their resources representation format for their communication and handshakes during their usual course of communication.

As we saw in Chapter 2, Design Strategy, Guidelines, and Best Practices, in the HTTP headers section, the HTTP specification comes up with a set of standard headers, through which the client can get information about a requested resource and carry the messages that indicate its representations.

So, for content negotiation, REST services need to use HTTP headers; that is, when the client makes requests, it includes the accepts header, the list of file types that the client and server can handle with no additional steps to the client requests, the server processes, and replies.

If the response representation selection is determined at the server-side, then it is server-driven negotiation or proactive negotiation using request-headers. If the same selection is at the client side, then it is agent-driven content negotiation or reactive negotiation using distinct a URI. For most practical purposes, server-side negotiations are more complex and lead to make many assumptions about client requirements. So, most of the REST API implementations follow agent-driven content negotiations that rely on the HTTP request headers or resource URI patterns.

Let us look at a quick and live example of content negotiation by going to the following link: http://www.w3.org/StyleSheets/TR/logo-REC. Observe that logo-REC is an image file; however, it does not have any file extension (that is, w3.org serving images without a file suffix), and the log-REC is not just one file, but two—loge-REC.gif and logo-REC.png. So, with content-negotiation the w3.org server serves two different files. The following screenshot explains a bit more about the request and response headers for the same:

Please observe the highlighted pieces from the preceding screenshot. The URL path, http://www.w3.org/StyleSheets/TR/logo-REC, does not say any file extension; however, in the response headers, observe the content-location and the content-type as image/png. The highlighted rectangles are quick examples of some of the content negotiation. Also please observe reactive negotiation through the request header accept.

Let's get into the details about content negotiation and the way the services/clients use them in the following paragraphs.