Content Negotiation

A main feature of the HyperText Transfer Protocol (HTTP) is that it allows clients and servers to negotiate what kind of formats both support. They do this using the Accept Header.

This allows implementation of APIs that are Backwards Compatible using Content Negotiation Versioning. Additionally this feature can be used to serve modern image and video formats to clients that indicate support for it.

Mechanism

1. When a client makes a request to a server it supplies all the formats it supports in the Accept Header: Accept: text/html,application/xhtml+xml.
2. The server looks at the list the client sent and excludes all formats it does not support.
3. If there are no common formats, the server either responds with 406 Not Acceptable or it picks a fallback format like text/html.
4. If there are common formats left, the server picks the one the client marked with the highest priority.
5. The server then returns the content that matches the negotiated format.

Wildcards

Sometimes clients want to specify general classes that they accept. This can be done by using a *. This allows clients to request things like imge types: (image/*), or anything at all: (*/*)

Content-Language Negotiation

Aside from negotiating the Content-Type of the response, HTTP also allows clients to negotiate the Content-Language of the returned data. This is done in the same way as above but then with the Accept-Language Header.

Best Practices

To make life easier for everyone we recommend following these practices:

Return a text/html Response by Default

Primarily if the request contains no Accept header or if the client asks for */*. Ideally this should show a browser friendly interface or an API Viewer. This allows users to use their browser to explore the data and makes it mandatory for clients to specify what response they want, an important step needed to allow Backward Compatibility.

Return a List of Supported Formats When Sending a 406 Not Acceptable

Ideally these should link to API Viewer screens that show the response so users can explore the API in their browser.