URI versioning, header versioning, deprecation policy, changelogs.

API Versioning — Managing Breaking Changes Without Breaking Clients

API versioning allows evolving an API while maintaining backward compatibility for existing clients. Breaking changes require a new version: removing fields, changing field types, renaming endpoints. Non-breaking changes do not require a new version: adding optional fields, adding new endpoints. URI versioning (/v1/, /v2/) is most discoverable but clutters base URLs. Header versioning is cleaner but harder to test. Deprecation policy (sunset date) gives clients time to migrate.

Interactive Pipeline Flow

UnderstandImplementOptimise

💥 Breaking — vs non-breaking

Breaking changes: removing fields, renaming fields, changing field types, changing required → optional, changing endpoint URLs, removing enum values. Non-breaking: adding optional fields, adding endpoints, adding enum values.

Architecture Diagrams

What requires a new version vs what can be added safely.

Loading diagram...

Key Design Decisions

💥Never remove fields — additive changes are always safe

Adding new optional response fields is a non-breaking change — old clients ignore unknown fields. Removing fields breaks all clients using that field. When you must remove, deprecate with a sunset date.

🌅Sunset header gives clients machine-readable deprecation notice

Add Sunset: <date> and Deprecation: true response headers from day one of deprecation. API clients that monitor these headers can auto-alert their teams. Much better than clients missing an email.

❄️Maintain at most 2 concurrent major versions

Supporting v1, v2, v3, v4 simultaneously quadruples maintenance burden. Aggressively deprecate. Target: current version + one previous (in sunset period). Everything older is gone.

Discussion