Course contentsShow
← Software Engineering
Lesson 791 of 1,93324. REST API DesignFree lesson

URI Versioning (Path-Based)

Implementing version numbers in the URL path (/v1/users) with pros, cons, and best practices.

URI Versioning (Path-Based)

What you'll learn: How to include version numbers directly in your API's URL path to manage changes gracefully over time.

The Core Idea

URI versioning (also called path-based versioning) places the API version number directly in the URL path itself, like /v1/users or /v2/products. This is the most visible and straightforward versioning approach, making it immediately clear which version a client is using.

How It Works

When you design your API endpoints, you include the version as the first segment of the path:

GET /v1/users
GET /v1/users/123
POST /v2/products

When you need to make breaking changes, you create a new version path (/v2/) while keeping the old one (/v1/) running simultaneously. Clients migrate at their own pace.

Pros

  • Highly visible: Anyone reading the URL knows exactly which version they're hitting
  • Easy to implement: No special headers or parsing logic needed
  • Simple routing: Most web frameworks handle path-based routing naturally
  • Cacheable: Since versions are in the URL, caching systems treat them as different resources

Cons

  • URL pollution: Version numbers clutter every endpoint
  • Duplicate code: You may maintain multiple versions of similar logic
  • Client burden: Clients must update all endpoint URLs when migrating
  • Not truly RESTful: Purists argue that versions shouldn't be part of resource identifiers

Best Practices

  • Start with v1, not v0 or 1.0
  • Keep version numbers simple (major versions only)
  • Document deprecation timelines clearly
  • Maintain at least N-1 versions (current plus previous)

Key Takeaway: URI versioning puts the version number directly in the URL path (/v1/users), offering maximum visibility and simplicity at the cost of URL clutter and maintenance overhead.