URI Versioning — The /v1/ Approach

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

URI versioning embeds the version in the URL path, making it visible, cacheable, and easy to route to different backend services.

Request Format

GET /api/v1/users
GET /api/v2/users

Implementation

const v1 = express.Router();
const v2 = express.Router();

v1.get("/users", (req, res) => {
  res.json({ version: "1.0", data: usersV1 });
});

v2.get("/users", (req, res) => {
  res.json({ version: "2.0", data: usersV2 });
});

app.use("/api/v1", v1);
app.use("/api/v2", v2);

Trade-offs

Pros: Simple, explicit, cache-friendly, easy to route, visible in logs. Cons: URL pollution, violates REST consistent URI principle, requires URL changes.

Common Mistakes

1. Version in resource URL — /api/v1/users/v1 instead of /api/v1/users.
2. No version in default route — Unversioned /api/users is ambiguous.
3. Version after resource — /users/v1 instead of /v1/users.

Practice Questions

1. What are the advantages of URI versioning?
2. What are the disadvantages?
3. Where should the version appear in the URL?

Challenge

Implement URI versioning for a task API with v1 and v2. v2 adds a priority field to tasks. Route requests to the correct version handler.

What's Next

In the next lesson, you will learn header versioning.