URI Versioning (Path-Based)
What you'll learn: How to encode API versions directly in URL paths to maintain backward compatibility and clarity.
What Is URI Versioning?
URI versioning (also called path-based versioning) embeds the API version number directly in the resource path. Instead of a single endpoint like /users, you'd have /v1/users, /v2/users, etc. This is the most visible and explicit versioning strategy.
When your API evolves—adding fields, changing validation rules, or restructuring responses—you create a new version path rather than breaking existing clients. A mobile app using /v1/users continues working unchanged while new clients adopt /v2/users with enhanced features.
How It Works
Each major version gets its own path segment:
GET /v1/users/123
GET /v2/users/123
POST /v1/orders
POST /v2/orders
Clients explicitly choose which version to call. Your routing layer directs requests to version-specific handlers or controllers.
Pros
- Crystal clear: Version is immediately visible in URLs and logs
- Easy routing: Most frameworks handle path-based routing naturally
- Browser-friendly: Works seamlessly in browsers, cURL, and documentation
- Caching-friendly: Different versions can have independent cache policies
Cons
- URL bloat: Every endpoint carries version prefix
- Not strictly RESTful: Purists argue the resource (
/users/123) shouldn't change identity based on representation - Multi-version maintenance: You must maintain parallel codebases or clever abstraction layers
Best Practices
- Use only major versions in paths (
/v1, not/v1.2.3) - Handle minor/patch changes within the same major version
- Provide clear deprecation timelines for old versions
- Document differences between versions thoroughly
Key Takeaway: URI versioning makes API versions explicit and easy to route, ideal when clarity and simplicity outweigh RESTful purity concerns—just be prepared to maintain multiple versions simultaneously.