Content negotiation allows a client to express which representation it can accept. JSON is common for web APIs, but some integrations may need CSV exports, binary documents or a different representation version. The server should make this behavior explicit rather than infer it from a file extension or an undocumented query parameter.
Respect Accept and Content-Type
Content-Type describes the request body format. Accept describes response formats the client can handle. Validate both. If the request body uses an unsupported media type, respond with 415 Unsupported Media Type. If the server cannot produce any acceptable representation, respond with 406 Not Acceptable when that is the chosen contract. Document supported media types and parameters.
Keep representation logic isolated
Use a serializer or presenter for each supported representation. Do not mix CSV escaping, JSON serialization and business rules in a controller. A CSV export needs its own rules for delimiters, quoting, character encoding and spreadsheet formula injection. A binary response needs correct content length and streaming behavior.
Protect caches
If the response changes based on Accept, send an appropriate Vary: Accept header. If it also depends on language or authorization, account for those dimensions. Private or user-specific data should not be stored in shared caches merely because it is a GET response.
Avoid needless complexity
Do not support multiple formats without a real consumer requirement. Every additional representation expands testing, documentation and security review. Prefer a stable JSON API plus a dedicated export endpoint when that is clearer for clients.
Further reading
- RFC 9110: Content Negotiation — https://www.rfc-editor.org/rfc/rfc9110
- MDN: Accept header — https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept