API versioning

API Design

Meaning

API versioning is the practice of tagging and exposing distinct versions of an API so that clients can continue using older contracts after the server evolves. It addresses the pain point of breaking existing consumers when an API's schema, endpoints, or behavior change. Developers reach for it whenever a published interface must evolve without forcing coordinated upgrades across all clients.

Primary Function

API design

Communicative Purpose

Ensures backward compatibility while allowing the API surface to evolve over time.

Pattern

identify breaking change → choose versioning scheme (URI path, header, query param) → publish new version → deprecate old version with sunset policy

Função primária

API design

Propósito comunicativo

Ensures backward compatibility while allowing the API surface to evolve over time.

Situações de gatilho

Web services: introducing breaking changes to a public REST endpoint while keeping legacy clients alive; Microservices: coordinating contract changes across independently deployed teams; SDK distribution: shipping a new client library that must coexist with older server versions.

Contextos

REST APIs, GraphQL schemas, gRPC services, public cloud platforms (AWS, Azure, GCP), OpenAPI/Swagger specifications, internal microservice meshes.

Padrão

identify breaking change → choose versioning scheme (URI path, header, query param) → publish new version → deprecate old version with sunset policy

Colocados típicos

URI path versioning (/v1/
/v2/)
Accept header versioning
deprecation policy
sunset header
backward compatibility
semantic versioning
OpenAPI spec
API gateway routing.

Substituições comuns

URI path versioning (e.g. /v2/users) — simple and cacheable but pollutes the URL space
header-based versioning (Accept: application/vnd.api+json
v=2) — cleaner URLs but harder to debug
query parameter versioning (?version=2) — easy to add but easy to forget. Each trades discoverability against URL aesthetics.

Erros comuns

Versioning every change as breaking — causes version sprawl and confuses clients who expected backward-compatible additions; Forgetting to version error response schemas — clients parsing old error formats break silently; Using the same version number for incompatible changes — defeats the contract clients rely on; Treating internal refactors as breaking versions — wastes client upgrade effort; Neglecting a deprecation timeline — leaves clients with no migration runway.

Similar / contraste

Semantic versioning — applies to libraries/packages, not live network APIs; API gateway routing — the mechanism that dispatches requests to versioned backends; Feature flags — toggle behavior per client without changing the URL or contract; Blue-green deployment — switches traffic between versions but doesn't expose multiple versions simultaneously.

Interferências

Coming from library/package ecosystems: may assume SemVer-style major bumps are sufficient — live network APIs need explicit deprecation windows and dual-running periods because clients cannot be force-upgraded. Coming from internal-only systems: may skip versioning entirely — once an API is consumed by external or cross-team clients, versioning becomes mandatory.

Família do chunk

API contract
backward compatibility
deprecation policy
semantic versioning
API gateway routing
OpenAPI specification

Nuance

Avoid versioning for purely additive, backward-compatible changes — it creates maintenance burden without consumer benefit. Resource cost is modest (duplicate routing rules, possibly duplicate backends during overlap windows) but operational complexity grows with the number of simultaneously supported versions. Boundary condition: a version is only meaningful if clients can actually pin to it; undocumented or unrouteable versions provide no compatibility guarantee.

Efeito pragmático

Lets a product evolve its API surface continuously without coordinating a flag-day migration with every consumer, turning breaking changes into a managed, time-boxed transition.

Dica de memória

API versioning is like apartment building numbering — when you renovate unit 2B, the tenants in 2A keep their mail flowing until they're ready to move.

Upgrade path

API deprecation policy and sunset headers — the operational machinery that makes versioning a managed transition rather than a permanent fork.

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

Examples

# URL-path versioning in a Flask API from flask import Flask, jsonify app = Flask(__name__) @app.route("/v1/users/<int:user_id>") def get_user_v1(user_id): return jsonify({"id": user_id, "name": "Alice", "email": "alice@example.com"}) @app.route("/v2/users/<int:user_id>") def get_user_v2(user_id): return jsonify({"id": user_id, "profile": {"name": "Alice", "contact": {"email": "alice@example.com"}}}) # Both versions run simultaneously; clients migrate at their own pace.

// Header-based versioning in Express.js const express = require("express"); const app = express(); function versionRouter(req, res, next) { const accept = req.headers["accept"] || ""; if (accept.includes("version=2")) return v2Handler(req, res); return v1Handler(req, res); } function v1Handler(req, res) { res.json({ items: ["a", "b"] }); } function v2Handler(req, res) { res.json({ items: ["a", "b"], cursor: "next-page" }); } app.get("/items", versionRouter); app.listen(3000);

# OpenAPI spec declaring two versions of the same endpoint openapi: 3.0.0 info: title: Orders API version: "2.1.0" paths: /v1/orders: get: responses: "200": description: Legacy order list (deprecated) headers: Sunset: schema: { type: string } description: "Date when /v1/orders will be removed" /v2/orders: get: responses: "200": description: Current order list with cursor pagination