The Accept header tells an HTTP server which response media types a client can process. It enables content negotiation: clients request a suitable representation while the server responds with the chosen format and identifies it with Content-Type. section 9.7.1
Make Accept optional when JSON is a useful default. Consumers that omit the header or send Accept: application/json receive JSON, while other consumers can request formats that better fit their tools or workflows. section 9.7.1 section 14.2.2
Use the header deliberately:
- Request CSV for transaction data when spreadsheet analysis is more convenient than JSON; the response can omit metadata that does not fit the CSV representation. section 9.7.1
- Request hypermedia representations such as application/hal+json or application/vnd.siren+json instead of application/json. section 11.4.4
- Keep request and response formats independent: Content-Type describes the submitted body, whereas Accept describes the desired response. A JSON request can ask for an XML response. section 9.7.1
- Support only formats justified by the operation, and apply a consistent policy across related operations. section 9.7.1 section 9.11
Requesting a spreadsheet-friendly response
GET /account/123/transactions Accept: text/csv HTTP/1.1 200 OK Content-Type: text/csv When a client sends no Accept header, the same operation returns JSON by default. If a POST /transfers body uses an unsupported format, a 415 response can include Accept: application/json, application/xml and an explanatory error body. section 9.7.1 section 9.8.3
Figure 9.11 Content negotiation allows consumers to request an account’s transactions in different formats by sending a standard Accept header.
Visualizes how a standard Accept header lets an account-transactions endpoint return different representations. section 9.7.1
