Content Negotiation — Media Type Versioning

In this tutorial, you will learn about Content Negotiation. We cover key concepts, practical examples, and best practices to help you master this topic.

Content negotiation versioning uses the standard HTTP Accept header with custom media types to specify the desired API version and response format simultaneously.

Request Format

GET /api/users
Accept: application/json; version=2
Accept: application/vnd.dodatech.v2+json

Implementation

app.get("/api/users", (req, res) => {
  const accept = req.headers["accept"] || "";
  const version = accept.includes("version=2") ? "2.0" : "1.0";

  if (version === "2.0") {
    return res.json({ version: "2.0", data: usersV2 });
  }
  res.json({ version: "1.0", data: usersV1 });
});

Trade-offs

Pros: Uses standard HTTP mechanism, clean URLs, supports multiple formats. Cons: Complex to implement, less discoverable, harder to test.

Common Mistakes

1. Not handling Accept header absence — Default to latest version.
2. Ignoring quality values — Accept header can include q values for preference.
3. No format negotiation — Not sending Content-Type for response format.

Practice Questions

1. How does content negotiation versioning work?
2. What is the role of the Accept header?
3. What are the advantages of using standard HTTP mechanism?

Challenge

Implement content negotiation versioning supporting multiple media types and versions. Parse the Accept header to determine version and response format.

What's Next

In the next lesson, you will learn version formats.