Content Negotiation

Content negotiation allows clients and servers to agree on the format of request and response data. This enables a single endpoint to serve different formats.

How It Works

Content negotiation uses HTTP headers:

Header	Purpose	Example
Accept	What format client wants	Accept: application/json
Content-Type	Format of request body	Content-Type: application/json

The Accept Header

Clients use Accept to specify desired response format:

GET /api/users/123
Accept: application/json

GET /api/users/123
Accept: application/xml

GET /api/users/123
Accept: text/csv

Multiple Types with Priority

Clients can specify preferences:

Accept: application/json, application/xml;q=0.9, */*;q=0.8

• application/json - Priority 1.0 (default)
• application/xml;q=0.9 - Priority 0.9
• */*;q=0.8 - Any format, priority 0.8

The Content-Type Header

In Requests

Tells the server what format the request body is in:

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

{"name": "Alice"}

In Responses

Tells the client what format the response is in:

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

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

Common Content Types

Content Type	Description
application/json	JSON data
application/xml	XML data
text/plain	Plain text
text/html	HTML
text/csv	CSV data
application/pdf	PDF document
multipart/form-data	File uploads
application/x-www-form-urlencoded	Form data

Handling Unsupported Formats

When the server can't provide the requested format:

GET /api/users
Accept: application/xml

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

{
  "error": {
    "code": "NOT_ACCEPTABLE",
    "message": "Requested format not supported",
    "supported": ["application/json"]
  }
}

Exercise: Content Negotiation Handler

Versioning via Content Type

Some APIs use content types for versioning:

Accept: application/vnd.myapi.v2+json

This is called "vendor" content types.

Character Encoding

Specify character encoding with charset:

Content-Type: application/json; charset=utf-8

UTF-8 is the standard for JSON.

Best Practices

1. Default to JSON - Most clients expect JSON
2. Always set Content-Type - In both requests and responses
3. Return 406 for unsupported formats - Be explicit about what's supported
4. Document supported formats - List in API documentation
5. Use UTF-8 - Standard encoding for modern APIs

Summary

Header	Direction	Purpose
Accept	Request	Client's preferred format
Content-Type	Request	Format of request body
Content-Type	Response	Format of response body

Content negotiation enables flexible APIs that can serve multiple formats from the same endpoints.