# API Evolution

API discipline for changing interfaces that already have consumers.

## Rules

1. **Additive changes are safe. Breaking changes are expensive.** New optional fields, new endpoints, new query parameters — ship freely. Removing, renaming, or changing types — that's a breaking change with a migration plan.

2. **Version explicitly when you break.** URL versioning, header versioning, or a new endpoint — pick a strategy and stick to it. Silent breaking changes destroy consumer trust.

3. **Deprecation is a process, not an event.** Announce, document the replacement, set a sunset date, monitor usage of the old path, then remove. "We removed it" without warning is how you lose integrators.

4. **Consumers are part of the contract.** Mobile apps you don't control, third-party integrations, internal services on old versions — you don't know who's calling what. Assume someone still uses the old shape.

5. **Response shape changes are breaking changes.** Making a field nullable, changing an array to an object, renaming a key — these break parsers. Treat them like deleted endpoints.

6. **Changelog every change.** What changed, why, who it affects, what consumers need to do. An API without a changelog is an API consumers learn about by breaking.

## What This Replaces

Silent breaking changes, "just update your client" without migration paths, and treating APIs as internal-only when external consumers exist.