Choosing a representation
A single URL can have several representations, such as JSON or HTML, English or French, compressed or plain. Content negotiation is the process by which the client states its preferences and the server picks the best representation it can serve.
How it works
- The client sends Accept to list acceptable media types like JSON or HTML.
- Accept Language lists preferred languages, and Accept Encoding lists compression schemes.
- Each preference can carry a quality value from zero to one to rank options.
- The server picks a match and echoes the chosen type in the Content Type header.
This is server driven negotiation, the most common form. To keep caches correct, the server adds a Vary header naming which request headers influenced the choice, so a cache does not serve a French page to a client that asked for English. If the server cannot satisfy the constraints, it may return a not acceptable status or fall back to a sensible default representation.
Key idea
Content negotiation lets a client express format and language preferences so the server returns the best representation.