Definition
When an API needs to evolve and introduce breaking changes, how do you let old clients keep working while new clients get new features? URI path versioning is the most straightforward answer: put the version number right in the URL where everyone can see it. Instead of /api/users, you have /api/v1/users or /api/v2/users. Simple, explicit, impossible to miss.
This approach has become the most popular versioning strategy for public APIs, and for good reason. When a developer looks at API documentation or inspects network requests, the version is immediately visible. There is no hunting through headers or content types - the version is right there in the URL. This explicitness makes onboarding easier, debugging simpler, and API evolution clearer.
The trade-off is that purists argue URLs should identify resources, not versions - /users/123 is the user, regardless of API version. But in practice, different API versions often return different resource representations, so the URL distinction makes sense. Twitter, GitHub, Stripe, and most major APIs use path versioning because its benefits - clarity, cacheability, and simplicity - outweigh the theoretical impurity.
Example
Twitter API: Twitter uses /2/tweets for their v2 API, while the older /1.1/statuses/show.json served v1.1. Developers can clearly see which version their code targets.
GitHub API: GitHub’s REST API uses path versioning implicitly through different base URLs and explicitly in headers, but their GraphQL API uses a stable endpoint. The hybrid approach shows how different needs lead to different strategies.
Stripe API: Stripe uses date-based versioning in headers but maintains stable URL paths. When they introduced v2 of specific resources, they used clear path prefixes.
Google APIs: Many Google APIs use path versioning like /v1/projects or /v2/files, making it immediately clear which version you are integrating with.
Analogy
The Building Floors: Imagine an office building where different versions of a company occupy different floors. Marketing v1 is on floor 1, Marketing v2 with the new team structure is on floor 2. When you need marketing services, you know exactly which floor to visit based on which “version” you need. URI path versioning puts API versions on different “floors” of the URL.
The Store Departments: A department store might reorganize over time. The old electronics layout is in “wing A,” the new layout is in “wing B.” Signs clearly direct you. URI versioning puts clear signs in the URL.
The Highway Exits: Highways have numbered exits that do not change once established. New destinations get new exit numbers rather than renaming old ones. API path versions work similarly - v1 stays v1, and new features get v2.
The Book Editions: Bookstores stock different editions of textbooks. The “5th edition” shelf is separate from the “6th edition” shelf. Students know exactly which to buy. URI versioning shelves API versions separately.
Code Example
// URI path versioning
GET https://api.company.com/v1/customers/123
GET https://api.company.com/v2/customers/123
GET https://api.company.com/v3/customers/123
// Can also use major.minor
GET https://api.company.com/v2.1/customers/123
// Response v1 (simple)
{
"id": 123,
"name": "ACME Corp"
}
// Response v2 (enhanced)
{
"id": 123,
"name": "ACME Corp",
"tier": "enterprise",
"createdAt": "2024-01-15T10:00:00Z"
}