Content Negotiation

A single resource can have several representations — JSON, CSV, different languages. Content negotiation lets the client state a preference and the server pick the best match, all without changing the URI.

How it works

The client sends Accept (which media types it wants) and optionally Accept-Language; the server replies with the chosen representation and a matching Content-Type:

GET /reports/42 HTTP/1.1
Accept: text/csv, application/json;q=0.8
Accept-Language: th, en;q=0.5

The q values are quality weights — here the client prefers CSV, then JSON. The server should honor the best type it supports and echo it in Content-Type.

When it cannot comply

If the server cannot produce any accepted type, respond 406 Not Acceptable.
If a request body arrives in a type the server cannot parse, respond 415 Unsupported Media Type.

Negotiating in a running API

JavaScript

const report = { id: 42, total: 99 };

app.get('/reports/:id', (c) => {
  const accept = c.req.header('Accept') ?? 'application/json';
  if (accept.includes('text/csv')) {
    return c.body('id,total\n' + report.id + ',' + report.total, 200, {
      'Content-Type': 'text/csv',
    });
  }
  if (accept.includes('application/json') || accept.includes('*/*')) {
    return c.json(report);
  }
  return c.json({ title: 'Not Acceptable', status: 406 }, 406);
});