HTTP Content Negotiation in REST APIs

What Is Content Negotiation?

Content negotiation is the mechanism by which an HTTP client and server agree on the format, language, and encoding of the response. The client advertises its capabilities and preferences via Accept headers; the server selects the best match and responds with the chosen format in the Content-Type header.

# Client requests JSON, but also accepts XML (lower priority)
GET /products/42 HTTP/1.1
Host: api.example.com
Accept: application/json, application/xml;q=0.9
Accept-Language: en-US, en;q=0.8, es;q=0.5
Accept-Encoding: gzip, br

# Server responds with best match
HTTP/1.1 200 OK
Content-Type: application/json
Content-Language: en-US
Content-Encoding: gzip

{ "id": 42, "name": "Widget" }

Server-Driven vs Client-Driven Negotiation

Almost all REST APIs use server-driven negotiation — the client sends Accept headers, the server decides.

Accept-Language: Language Negotiation

The Accept-Language header lets clients request responses in a preferred language. Useful for internationalised APIs returning translated content, error messages, or date formats. Defined in RFC 9110 §12.5.4.

Accept-Language: en-US           # US English only
Accept-Language: en-US, en;q=0.9 # US English preferred, then any English
Accept-Language: es, en;q=0.7    # Spanish preferred, English fallback
Accept-Language: *               # Any language

The server should respond with the Content-Language header indicating the actual language of the response body:

Content-Language: en-US
Content-Language: es

Node.js: Language Negotiation

const i18n = {
  'en': { greeting: 'Hello' },
  'es': { greeting: 'Hola' },
  'fr': { greeting: 'Bonjour' }
};

app.get('/greet', (req, res) => {
  // req.acceptsLanguages() returns best match
  const lang = req.acceptsLanguages(['en', 'es', 'fr']) || 'en';

  res.set('Content-Language', lang);
  res.json({ message: i18n[lang].greeting });
});

Practical note: Most REST APIs default to English and use the lang or locale query parameter instead (GET /messages?lang=es). This is less pure REST but more cache-friendly (different URLs = different cache keys).

API Versioning via Accept Header

Some APIs use the Accept header for versioning instead of URL paths. This keeps URLs clean but makes testing harder (you can't just paste a URL in a browser).

# GitHub API v3 style — vendor media type with version
Accept: application/vnd.github.v3+json

# Custom version parameter
Accept: application/json; version=2

# Full vendor type with version
Accept: application/vnd.myapi.v2+json

Node.js: Header-Based Versioning

app.get('/users/:id', (req, res, next) => {
  const accept = req.headers['accept'] || 'application/json';

  // Extract version from vendor media type
  const v2Match = accept.match(/application\/vnd\.myapi\.(v\d+)\+json/);
  const version = v2Match ? v2Match[1] : 'v1';

  if (version === 'v2') {
    return res.json(serializeUserV2(user));
  }
  return res.json(serializeUserV1(user));
});

For most APIs, URL versioning (/v2/users) is simpler, more cacheable, and easier to document. Use header versioning only if clean URLs are a strict requirement. See our Versioning Guide for a full comparison.

Frequently Asked Questions

Should I always implement content negotiation?

For most REST APIs: no. If your API only serves JSON, just always return Content-Type: application/json. Implement content negotiation when you genuinely need to serve multiple formats (JSON, XML, CSV) or when you are building a versioned API that uses vendor media types.

What happens if a client sends no Accept header?

Per RFC 9110 §12.5.1, an absent Accept header is equivalent to Accept: */* — the client accepts any media type. The server should return its default format (typically JSON for REST APIs).

Is content negotiation the same as API versioning?

No, but they can be combined. Content negotiation selects the format of the response (JSON vs XML). Versioning selects the schema/structure of the response (v1 vs v2 fields). Some APIs combine both using vendor media types like application/vnd.myapi.v2+json, which simultaneously specifies the format (JSON), the vendor, and the version.

Does content negotiation affect HTTP caching?

Yes. If a resource can be served in multiple formats depending on the Accept header, the cache key must include the Accept header value — otherwise a cached JSON response could be served to a client that requested XML. The Vary: Accept response header tells caches to include the Accept value in the cache key:

Vary: Accept, Accept-Language, Accept-Encoding