API Versioning Strategies for APIs Other Teams Depend On

An internal API used by one team can get away with breaking changes and a Slack message. An API consumed by external clients, mobile apps still in app-store review, or partner integrations cannot — and the versioning discipline that protects those consumers has to exist before the first breaking change, not after.

• URL versioning (`/v1/`, `/v2/`) is the most explicit and the easiest for consumers to reason about, even if it's less elegant.
• Add fields freely without a version bump; only bump on removal or semantic change to an existing field.
• Deprecation headers and a real sunset date, communicated well in advance, beat a silent breaking change every time.
• Keep the previous version running until usage metrics show it's actually safe to retire, not until the calendar says it should be.

The teams that get this wrong usually aren't bad at API design — they just didn't decide on a versioning strategy until the first breaking change was already needed, which is precisely the worst time to design it under pressure.

Version your API before you need to break it. Deciding under pressure is how you break someone's production system by accident.