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, notv0or1.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.