API Versioning

The moment someone else's code calls your API, its shape is a promise. Versioning is how you keep the promise and still move: v1 keeps behaving exactly as documented while new work lands in v2. Three common carriers, in order of how often you will meet them: a URL prefix (/v1/users), a header (Accept: application/vnd.acme.v2+json), and a dated version pinned per account, which is how Stripe does it.

The actual skill is knowing what counts as breaking. Adding an optional field, adding an endpoint, accepting a new optional parameter: safe, and no version bump needed. Renaming or removing a field, tightening validation, changing a type, changing a default, changing error codes, or adding a new enum value clients must handle: breaking. Staying additive is the cheapest possible outcome, so exhaust it first.

Gotcha: every version you ship is a version you maintain, bugs included. Keep the business logic in one shared service layer and a bug fixed there is fixed everywhere; what multiplies is the version-specific surface, the request and response mapping, the docs, and the test suites, which you write and rerun once per live version. Launch a new version alongside a written sunset date and real telemetry on who still calls the old one, or v1 outlives you. And clients will depend on behavior you never documented, so publish the contract as an OpenAPI spec; otherwise 'breaking' has no agreed definition to argue from.