Every API eventually needs to change in ways that break existing clients. The question isn’t whether to version — it’s how to version in a way that doesn’t make your users hate you. Here’s what actually works, with real trade-offs. The Three Schools of Versioning URL Path Versioning G G E E T T / / a a p p i i / / v 1 2 / / u u s s e e r r s s / / 1 1 2 2 3 3 Pros: ...
APIs are contracts. Breaking changes break trust. But APIs must evolve—new features, better designs, deprecated endpoints. The question isn’t whether to change, but how to change without leaving clients stranded. Why Versioning Matters Without versioning, you have two bad options: Never change: Your API calcifies, accumulating cruft forever Change freely: Clients break unexpectedly, trust erodes Versioning gives you a third path: evolve deliberately, with clear communication and migration windows. Versioning Strategies URL Path Versioning The most explicit approach—version in the URL: ...
APIs evolve. Fields get renamed, endpoints change, entire resources get restructured. The question isn’t whether to version your API—it’s how to do it without breaking every client that depends on you. Versioning Strategies 1. URL Path Versioning The most visible approach—version is part of the URL: G G E E T T / / a a p p i i / / v 1 2 / / u u s s e e r r s s / / 1 1 2 2 3 3 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 from fastapi import FastAPI, APIRouter app = FastAPI() # Version 1 v1_router = APIRouter(prefix="/api/v1") @v1_router.get("/users/{user_id}") async def get_user_v1(user_id: int): return { "id": user_id, "name": "John Doe", "email": "john@example.com" } # Version 2 - restructured response v2_router = APIRouter(prefix="/api/v2") @v2_router.get("/users/{user_id}") async def get_user_v2(user_id: int): return { "id": user_id, "profile": { "name": "John Doe", "email": "john@example.com" }, "metadata": { "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-02-11T00:00:00Z" } } app.include_router(v1_router) app.include_router(v2_router) Pros: Explicit, easy to understand, easy to route Cons: URLs change between versions, harder to maintain multiple versions ...