What are the best practices for HTTP content negotiation?

1 Negotiation strategy

There are three main types of content negotiation: server-driven, agent-driven, and transparent. Server-driven negotiation relies on the server to select the best representation based on the client's request headers, such as Accept, Accept-Language, or Accept-Encoding. Agent-driven negotiation requires the server to provide a list of alternatives and let the client choose one, such as with the 300 Multiple Choices status code or the Link header. Transparent negotiation combines both approaches, using a third-party intermediary or a cache to facilitate the selection. The best strategy depends on your use case, but generally, server-driven negotiation is preferred for simplicity and efficiency, agent-driven negotiation is useful for user preference and control, and transparent negotiation is beneficial for scalability and performance.

2 Standard headers and parameters

To implement content negotiation, you should use the standard HTTP headers and parameters that indicate the client's and server's preferences and capabilities. The most common ones are Accept, Accept-Language, Accept-Encoding, Accept-Charset, Content-Type, Content-Language, Content-Encoding, and Vary. Quality values (q) can be used to indicate relative preferences for each of these headers. Additionally, query parameters or URI extensions can be used to indicate the desired representation; however, this is less flexible and interoperable than using headers. When using content negotiation, it's important to consider how your approach may affect the semantics and cacheability of the resource.

3 Errors and fallbacks

Sometimes, content negotiation may fail due to incompatible or invalid preferences or capabilities. For example, the client may request a media type that the server does not support, or the server may send a representation that the client cannot handle. In these cases, you should follow HTTP standards and best practices for handling errors and fallbacks, such as sending a 406 Not Acceptable status code if the server cannot provide a representation that matches the client's preferences. Additionally, you should send a 415 Unsupported Media Type status code if the server cannot process the representation sent in the request body. If either the client or the server sends a malformed or invalid header or parameter, you should send either a 406 Not Acceptable or a 415 Unsupported Media Type status code. Finally, if the client does not specify any preferences or capabilities, or if the server cannot determine them, you should send a default or generic representation. You can also include alternatives and hints in the response body or Link header.

4 Testing and debugging

To ensure that your content negotiation works as expected, you should test and debug it using various tools and methods. For instance, you can use a web browser or command-line tool to send different requests with headers and parameters and inspect the responses. Additionally, a web proxy or network analyzer can be used to capture and analyze HTTP traffic between the client and the server, allowing you to observe the content negotiation process and results. Furthermore, web testing or development tools can be used to simulate and modify requests and responses, so that you can evaluate the content negotiation outcomes and performance. Lastly, web validators or linters can be employed to check and correct the syntax and semantics of your headers and parameters, thus avoiding common errors.

5 Caching and compression

Content negotiation can affect the caching and compression of your resources, and vice versa. Caching and compression can improve the performance and efficiency of your web application, but they require precise configuration and coordination. The Vary header should be used to inform caches that the representation of a resource depends on certain request headers. The ETag or Last-Modified header can provide validators for representations, while If-None-Match or If-Modified-Since headers can request conditional responses. Content-Encoding or Transfer-Encoding headers should indicate the encoding of representations, and Accept-Encoding or TE headers should indicate the encoding that the client or server can handle. This way, you can compress and decompress representations, reducing bandwidth and latency of your web application.

6 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?