 HTTP proactive negotiation

HTTP proactive negotiation is HTTP content negotiation in which the server selects an HTTP representation using information in the client's request. Explicit preferences can describe acceptable media types, languages or content encodings; the server can also use implicit request characteristics. The specification also calls this server-driven negotiation.^[ref]

Suppose /report offers both JSON and HTML. A client sends Accept: application/json, text/html;q=0.5. The omitted quality weight for JSON defaults to one, so the request expresses a stronger preference for JSON than for HTML. If the server honors this ranking and both forms are available, it returns the JSON form with Content-Type: application/json.^[ref]

This can deliver the preferred representation in the first response. The client does not first need to retrieve a menu of alternatives and then make another choice. In contrast, HTTP reactive negotiation leaves selection to the client after an initial response identifies alternatives. Either approach still requires the application to decide what the available representations mean.

A server selecting on Accept can send Vary: Accept. That field identifies an additional request dimension that might affect the response, beyond the method and target identifier. A stored response chosen for one Accept value is consequently not automatically the appropriate selection for another; caching must account for the relevant variation.^[ref]

The server's information is incomplete. A supported format need not be the best format for the user's intended task, and describing capabilities in every request can increase message size and disclose information about the client. The specification also permits servers to disregard negotiation preferences rather than return 406 when honoring them would leave no acceptable choice. The example's ranking policy is therefore a stated application assumption, not an unconditional protocol guarantee.^[ref]