← Back to principles

API

Change without breaking

What this means in practice

This applies to public and internal APIs, and not experience APIs

Treat deployment as a routine operational activity and release as a deliberate product decision. APIs should evolve through a managed lifecycle with clear versioning, backwards compatibility by default, and planned deprecation.

Additive changes are the norm, and breaking changes are introduced only through explicit new versions, with progressive rollout to avoid surprising consumers.

Why this matters

Teams need to ship continuously without destabilising integrations. When change is controlled and predictable, consumers can adopt APIs with confidence and upgrade on their own timelines. Clear lifecycle management prevents long-term drag from fossilised endpoints, reduces support burden, and enables faster internal iteration without accumulating compatibility debt.

Practices that meet this principle

  • Deploy continuously, and treat release as separate from deployment (for example: feature flags, configuration-driven exposure)

  • Version APIs from day one, with an explicit lifecycle for each version (active, deprecated, retired)

  • Make additive changes by default, and require ceremony for breaking changes

  • Introduce breaking changes only via new API versions (for example: new required fields, changed semantics)

  • Roll out features progressively (for example behind flags) rather than big-bang releases

  • Run deprecation as a process with timelines, communication, and migration guidance (not a backlog item)

  • Remove retired APIs once consumers have migrated (avoid keeping dead endpoints indefinitely)

Validation

A project meets this principle when:

  • Deployment to production can happen independently of releasing new behaviour to consumers

  • Every API version has documented status and lifecycle dates, including a deprecation plan where relevant

  • Breaking changes are delivered only through new versions, with clear upgrade guidance

  • Additive changes do not require consumer changes, and do not break existing clients

  • Retired APIs are removed after an agreed migration period, and are not left running indefinitely