URI versioning

API Design

Meaning

URI versioning embeds the API version directly in the resource path (e.g., /api/v1/users), making the version an explicit part of the URL contract. It addresses the pain point of breaking clients when an API evolves by routing old and new clients to different code paths transparently. Developers reach for it when a public API needs backward-incompatible changes without forcing all consumers to migrate at once.

Primary Function

API versioning

Communicative Purpose

Enables parallel operation of multiple API versions so clients can migrate on their own schedule without coordinated downtime.

Pattern

embed version segment in URI path → route to version-specific handler

Função primária

API versioning

Propósito comunicativo

Enables parallel operation of multiple API versions so clients can migrate on their own schedule without coordinated downtime.

Situações de gatilho

REST API design: introducing a breaking change to a resource schema while keeping old clients working

Contextos

REST APIs, public web APIs, microservices, OpenAPI/Swagger specifications, API gateways

Padrão

embed version segment in URI path → route to version-specific handler

Colocados típicos

API gateway
deprecation policy
backward compatibility
semantic versioning
OpenAPI spec

Substituições comuns

Header versioning (Accept: application/vnd.api.v2+json) — keeps URLs clean but harder to cache and debug

Erros comuns

Versioning only the resource, not the representation: /v1/users returning a different schema than documented → silent contract break

Similar / contraste

Header versioning: version lives in Accept header, not URL

Interferências

Coming from GraphQL: may assume a single schema endpoint suffices — GraphQL deprecates fields instead of versioning URLs, so URI versioning is unnecessary overhead

Família do chunk

header versioning
query parameter versioning
media type versioning
semantic versioning
API deprecation policy

Nuance

Avoid URI versioning for internal-only APIs where you control all clients — the URL noise adds no value. URI versioning makes caching straightforward because each version is a distinct cache key, but it also means every endpoint must be duplicated across versions, inflating documentation and test surface. Boundary case: when v1 and v2 share most behavior, consider feature flags or content negotiation instead of full URI duplication.

Efeito pragmático

Lets teams ship breaking changes without coordinating a global cutover, reducing deployment risk and giving clients a predictable migration window.

Dica de memória

URI versioning is like giving each edition of a book its own shelf label — readers grab the edition they want, and the library keeps both available until the old one is withdrawn.

Upgrade path

API deprecation policy and sunset headers (Sunset, Deprecation HTTP headers)

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

const express = require('express'); const app = express(); const v1Router = require('./routes/v1/users'); const v2Router = require('./routes/v2/users'); app.use('/api/v1/users', v1Router); app.use('/api/v2/users', v2Router); app.listen(3000);

from fastapi import FastAPI app = FastAPI() @app.get("/api/v1/items/{item_id}") async def read_item_v1(item_id: int): return {"id": item_id, "schema": "v1"} @app.get("/api/v2/items/{item_id}") async def read_item_v2(item_id: int): return {"id": item_id, "schema": "v2", "fields": ["name", "price"]}

@RestController @RequestMapping("/api/v1/orders") public class OrderControllerV1 { @GetMapping("/{id}") public OrderV1 getOrder(@PathVariable Long id) { return orderService.findV1(id); } }