Versioning

How breaking API changes are managed over time: URL versioning (/v1/), header versioning, or additive-only evolution.

Why we need this / what value this brings

Without a versioning strategy, the first breaking change either breaks every client simultaneously or forces you to freeze the API forever.

When to use this

Decide before the first breaking change is needed, not during an incident when a client is already broken.

How to use or implement this

Prefer additive-only changes (new optional fields) as long as possible; when a break is unavoidable, use a URL or header version and support the old version for a defined deprecation window.

Research questions

• What actually counts as a 'breaking' change (field removal vs field addition)?
• How do you deprecate an endpoint without breaking mobile clients that can't force-update?

---

Empty folder — drop notes, links, and findings here as you research.