Headers, Content Negotiation and Representations

HTTP separates the resource from its representations. Clients state preferences with Accept (media type), Accept-Language, Accept-Encoding; servers declare Content-Type, Content-Language, Content-Encoding and Vary (so caches store variants correctly). Use application/json (or a vendor type like application/vnd.acme+json if you version by media type), application/problem+json for errors, and 415 Unsupported Media Type / 406 Not Acceptable when negotiation fails. Prefer standard headers over custom X- headers; when you need custom ones, document them.

Headers every API designer should know

GET /reports/2026-q3 HTTP/1.1
Accept: text/csv;q=1.0, application/json;q=0.8
Accept-Encoding: br, gzip

HTTP/1.1 200 OK
Content-Type: text/csv; charset=utf-8
Content-Encoding: br
Vary: Accept, Accept-Encoding
Content-Disposition: attachment; filename="report-2026-q3.csv"

Common pitfalls

• Ignoring Accept and always returning JSON (or HTML error pages from proxies).
• Missing Vary, so caches serve the wrong variant.
• Putting auth tokens or secrets in custom headers that get logged.

Key points

• Resources vs representations
• Negotiate with Accept; declare with Content-Type
• Vary for correct caching

Further reading: RFC 9110: Content negotiation