# Versioning & Designing APIs That Last

The first version of an API is the easy part. You ship it, a few clients integrate, and it works. The
hard part starts the day after - because now there are people out there whose code *depends on yours*,
and they can't see the changes you make. You can't roll their integration back. You often don't even
know who they are. So a one-line "improvement" - renaming a field, tightening a type, dropping
something you thought nobody used - can quietly break someone's production system on a random Tuesday,
and the first you'll hear of it is an angry support ticket.

That's the shift this guide is built around: **an API is a promise to everyone who built on it.** Once
you internalize that, versioning and design stop being bureaucracy and become the obvious way to keep
that promise - what a breaking change actually is, the real trade-offs of every way to evolve an
API without breaking people, and the checklist that makes an API durable enough to live for years.

## How to read this

- **About to change a live API right now and want to know if it's safe?** Jump to
  [Phase 1: The Contract Is Forever](01-the-contract-is-forever.md) and check your change against the
  breaking-vs-safe cheat-card at the top.
- **Want API longevity to finally make sense?** Read in order - each phase builds on the last. Phase 1
  is the mindset, Phase 2 is how to evolve, Phase 3 is how to design so you rarely have to.

## The phases

1. **[The Contract Is Forever](01-the-contract-is-forever.md)** - once clients depend on your API, a
   breaking change breaks *them*, silently, in production. What counts as breaking (removing or
   renaming fields, changing types or meaning) versus a safe additive change - and the mindset shift
   that follows.
2. **[Versioning Strategies](02-versioning-strategies.md)** - how to evolve without breaking people:
   prefer additive changes; when you genuinely must break, version (URL `/v2/` vs. a header), run the
   old and new in parallel, and deprecate on a clear timeline with real communication. The real
   trade-offs of each path.
3. **[Designing for Longevity](03-designing-for-longevity.md)** - the durable-API checklist:
   consistent resource and error shapes, pagination from day one, idempotency keys for safe retries,
   rate limits, sensible defaults, and documentation people can actually use. Plus the trap of leaking
   your internal database structure into your public contract.

> Authentication and authorization for APIs (API keys, OAuth, scopes, token rotation) are a security
> topic in their own right and live in the future **security** category - we point there lightly where
> it matters rather than rushing it here.

**Related:** [REST APIs, Explained](/guides/rest-apis-explained) ·
[Webhooks and Message Queues](/guides/webhooks-and-message-queues)