Designing Evolvable Web APIs with ASP.NET

Appendix C. Content Negotiation

There are two types of content negotiation (conneg): proactive and reactive.

Proactive Negotiation

This type of negotiation occurs when the server is responsible for selection and contains logic that executes per request in order to find the best representation. It makes the selection based on matching up against client preferences or additional headers and the server’s available representations. The client expresses its preference through the previously mentioned Accept* headers (see Table B-2). Each of these headers allows for sending multiple values or ranges along with a qualifier (also known as a q-value) that contains prioritization. The server can use additional fields, though, like User-Agent or any other.

If the server determines that the client hasn’t sent it enough information to make a selection it can make a default selection, return a status 406 Not Acceptable, or perform reactive negotiation (see next section). Once it makes the selection the server should return to the client the chosen representation. The response should include a Vary header, which indicates exactly which header fields were used to make the selection. The server can also include a Content-Location header containing the URI of the negotiated content. It is important to remember that the server is not bound by the client preferences, but it should try to adhere to them as much as it can.

Figure C-1 indicates the steps of the process.

Figure C-1. Proactive conneg

Notice in ...