Versioning & Designing APIs That Last

An API is a promise to everyone who built on it: what counts as a breaking change, how to evolve without breaking clients (additive-first, then versioning + deprecation), and the durable-API checklist - consistent shapes, pagination, idempotency, rate limits, and great docs.

1. The Contract Is Forever The moment a client depends on your API, a breaking change breaks them silently in production; this phase defines what counts as breaking (removing or renaming fields, changing types or meaning) versus a safe additive change, and the mindset that follows.
2. Versioning Strategies How to evolve an API without breaking clients: prefer additive changes, and when you must break, version (URL /v2/ vs header), run versions in parallel, and deprecate on a clear timeline with real communication - with the real trade-offs of each approach.
3. Designing for Longevity The durable-API checklist: consistent resource and error shapes, pagination from day one, idempotency keys for safe retries, rate limits, sensible defaults, and great docs - plus the trap of leaking your internal database structure into your public contract.