What Is Content Negotiation in REST APIs?

What Is Content Negotiation in REST APIs?\n\nContent negotiation is the mechanism that allows a REST API to deliver different representations of the same resource based on what the client can accept. Instead of building separate endpoints for JSON, XML, or PDF, a single URL can serve multiple formats dynamically.\n\nThink of it like ordering a coffee. You ask for a latte. The barista asks: "Whole milk or oat? Regular or extra shot? Hot or iced?" You get the same base drink, customized to your preference. Content negotiation works the same way: the client tells the server its preferences, and the server responds with the best match.\n\n\n\n\n\n## How Content Negotiation Works\n\nHTTP headers carry the negotiation. The client sends an `Accept` header listing preferred media types with quality values. The server inspects these headers and returns the closest supported format.\n\n| Step | Who | Action |\n|------|-----|--------|\n| 1 | Client | Sends `Accept: application/json` |\n| 2 | Server | Parses media types and q-values |\n| 3 | Server | Matches against supported formats |\n| 4 | Server | Returns response with `Content-Type` |\n| 5 | Client | Parses response using declared format |\n\n## The Accept Header\n\nThe `Accept` request header is the primary driver of content negotiation. Clients send it to specify which media types they can process.\n\n```\nAccept: application/json, text/xml;q=0.9, */*;q=0.1\n```\n\n| Value | Meaning |\n|-------|---------|\n| `application/json` | Strongly prefer JSON |\n| `text/xml;q=0.9` | Accept XML with lower priority |\n| `*/*;q=0.1` | Accept anything else as last resort |\n\nHigher `q` values means stronger preference. A value of `q=0` means the format is unacceptable.\n\n## Server-Driven vs Agent-Driven Negotiation\n\nThere are two negotiation strategies defined in HTTP.\n\n| Strategy | Who Decides | Mechanism | Use Case |\n|----------|-------------|-----------|----------|\n| Server-driven | Server | Accept, Accept-Charset, Accept-Encoding, Accept-Language | Traditional websites, APIs |\n| Agent-driven | Client | 300 Multiple Choices response with links | Complex APIs, HATEOAS |\n\nMost REST APIs use **server-driven negotiation** because it keeps the client simple. The server does all the matching logic and returns the best format in one request.\n\n## Common Media Types\n\nREST APIs commonly negotiate over these media types.\n\n| Media Type | Format | Typical Use |\n|-----------|--------|-------------|\n| `application/json` | JSON | Modern APIs, SPAs, mobile apps |\n| `application/xml` | XML | Legacy systems, SOAP bridges |\n| `text/html` | HTML | Documentation, browser rendering |\n| `text/plain` | Plain text | Logs, debugging, simple clients |\n| `application/pdf` | PDF | Invoices, reports, exports |\n| `application/octet-stream` | Binary | File downloads, images |\n\n## Vary Header and Caching\n\nWhen a server serves multiple representations from one URL, caching layers need to know the response varies by request headers.\n\n```\nVary: Accept, Accept-Encoding, Accept-Language\n```\n\nWithout the `Vary` header, CDNs and browsers may cache a JSON response and serve it to an XML client by mistake.\n\n## Content Negotiation and API Versioning\n\nSome teams use content negotiation to version APIs instead of URL versioning.\n\n| Approach | Example | Pros | Cons |\n|----------|---------|------|------|\n| URL versioning | `/api/v2/users` | Clear, explicit | Requires new endpoints |\n| Media type versioning | `Accept: application/vnd.example.v2+json` | Single URL, rich metadata | Complex headers |\n| Header versioning | `X-API-Version: 2` | Simple | Non-standard |\n\n**Best practice:** Combine URL versioning for major breaking changes and media type versioning for granular format control.\n\n## Related Keywords\n\nDevelopers also search for these terms:\n\n- **content negotiation REST API** — how servers choose response formats\n\n- **REST API content negotiation** — Accept header and media types\n\n- **HTTP Accept header** — client preferences for JSON XML HTML\n\n- **content negotiation example** — real API requests and responses\n\n- **REST API media types** — MIME types for API representations\n\n- **JSON XML content negotiation** — serving multiple formats from one endpoint\n\n- **client-server content negotiation** — HTTP header-driven format selection\n\n- **HTTP content negotiation best practices** — Vary header caching and q-values\n\n- **REST API versioning content negotiation** — version APIs with media types\n\n- **Accept header best practices** — q-values wildcards and MIME types\n\n## Implementation Example\n\nA simple Express.js middleware showing server-driven content negotiation.\n\n```javascript\napp.get('/api/users/:id', (req, res) => {\n const accept = req.headers.accept || ''\n const userId = req.params.id\n const user = getUser(userId)\n\n if (accept.includes('application/xml')) {\n res.type('application/xml')\n return res.send(toXml(user))\n }\n\n res.type('application/json')\n res.send(user)\n})\n```\n\nFrameworks like Spring, Django REST Framework, and .NET have built-in content negotiation support that handles the matching logic automatically.\n\n## Conclusion\n\nContent negotiation in REST APIs lets you serve JSON, XML, HTML, or any format from a single endpoint. It keeps APIs flexible, reduces endpoint clutter, and improves client experience. Master the `Accept` header, support standard media types, set the `Vary` header for caching, and choose a versioning strategy that fits your ecosystem.