Content negotiation lets an HTTP client and server select a suitable representation format or language for a message. Clients request alternatives with headers such as Accept, Content-Type, and Accept-Language; servers identify the result with Content-Type. The technique helps different consumers use the same API without forcing one data format or locale. section 9.7.1 section 9.7.2
Apply content negotiation where the variation solves a real consumer need:
- Offer JSON by default while allowing alternatives such as CSV for spreadsheet users or XML for consumers with native XML tooling. section 9.7.1
- Keep request and response formats independent: a consumer can send JSON and request an XML response, or reverse the combination. section 9.7.1
- Translate human-facing values with Accept-Language, including language priorities such as fr;q=0.9, while leaving property names and machine-readable codes unchanged. section 9.7.2
- Apply formats consistently across comparable operations, but support only formats that make sense for each operation. section 9.10.3 section 9.7.1
- Use custom media types or the Prefer header when consumers need different resource models, but recognize that both choices are uncommon and may surprise developers. section 13.5.1
Transactions in the consumer’s preferred form
A spreadsheet user requests GET /accounts/12345/transactions with Accept: text/csv. The API returns CSV with Content-Type: text/csv. A consumer that omits Accept receives the default JSON representation. A banking client can instead POST /transfers with Content-Type: application/xml and request an XML or JSON response independently. section 9.7.1
Selecting a resource model
GET /accounts can return a summarized model when the client sends Accept: application/vnd.bankingapi.summarized+json, or a complete model when it sends Prefer: model=complete. The response identifies the selected representation with Content-Type or Preference-Applied. section 13.5.1
Figure 9.11 Content negotiation allows consumers to request an account’s transactions in different formats by sending a standard Accept header.
Use the figure to compare a standard Accept request with the negotiated transaction response. section 9.7.1
Figure 13.9 We can use a custom media type or preference to get the complete or summarized model on any read, list, or search operation.
Use the figure to compare custom media types and Prefer for summarized or complete resource models. section 13.5.1
