Content Negotiation with HTTP Methods

What Is Content Negotiation?

Content negotiation allows clients and servers to agree on the format of data exchanged. The client specifies preferred formats in request headers, and the server responds with the best match.

Key Headers

Header	Direction	Purpose
Accept	Request	What formats the client can handle
Content-Type	Both	The format of the body
Accept-Encoding	Request	Compression formats (gzip, br)
Accept-Language	Request	Preferred language

GET with Accept Header

GET /api/users/42 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

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

Same endpoint, different format:

GET /api/users/42 HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<user><id>42</id><name>Alice</name></user>

POST/PUT with Content-Type

When sending data, Content-Type tells the server how to parse the body:

POST /api/users HTTP/1.1
Content-Type: application/json

{ "name": "Bob" }

POST /api/users HTTP/1.1
Content-Type: application/x-www-form-urlencoded

name=Bob&email=bob%40example.com

POST /api/users HTTP/1.1
Content-Type: multipart/form-data; boundary=----FormBoundary

------FormBoundary
Content-Disposition: form-data; name="name"

Bob
------FormBoundary
Content-Disposition: form-data; name="avatar"; filename="photo.jpg"
Content-Type: image/jpeg

[binary data]
------FormBoundary--

406 Not Acceptable

If the server cannot produce a response in any of the client's accepted formats:

HTTP/1.1 406 Not Acceptable
Content-Type: application/json

{
  "error": "Supported formats: application/json, application/xml"
}

415 Unsupported Media Type

If the server does not understand the request body format:

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json

{
  "error": "Expected Content-Type: application/json"
}

Quality Values

Clients can specify preference weights:

Accept: application/json;q=1.0, application/xml;q=0.5, text/plain;q=0.1

The server picks the highest-quality format it supports.