Header Versioning — Custom Headers for API Version

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

Header versioning specifies the API version in HTTP headers, keeping URLs clean and following REST principles of content negotiation.

Request Formats

# Custom header
GET /api/users
X-API-Version: 2

# Accept header with vendor media type
GET /api/users
Accept: application/vnd.dodatech.v2+json

Implementation

app.get("/api/users", (req, res) => {
  const version = req.headers["accept"]?.includes("v2")
    ? "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: Clean URLs, REST-friendly, supports content negotiation. Cons: Harder to test in browsers, requires header modification, less visible to Caching layers.

Common Mistakes

1. No default version — Not handling missing version header.
2. Custom header not documented — Clients do not know the header exists.
3. Browser testing difficulty — Cannot test from browser address bar.

Practice Questions

1. What are the two header-based versioning approaches?
2. What are the advantages of header versioning?
3. What are the testing challenges?

Challenge

Implement header versioning with Accept header vendor media types. Support v1 and v2 with default to latest version.

What's Next

In the next lesson, you will learn query parameter versioning.