Course contentsShow
← System Design
Lesson 1899 of 1,91945. API Design and VersioningFree lesson

URI Versioning (Path-Based)

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

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.