API Versioning

When to use

• The user is changing an API response or request and needs to know if it breaks existing clients and requires a new version.
• The user must choose how to version an HTTP API — URI path, custom header, or media-type versioning.
• The user needs to retire an old API version and communicate deprecation and a sunset date to clients.

When NOT to use

• Do not cut a new API version for a purely additive, backward-compatible change such as adding an optional field or a new endpoint.
• Do not add a versioning scheme when a single team deploys the API and its only client together and can change both at once.

Core guidance

• Expose only the major version to clients — Surface only the major version (v1, v2) in the API surface and bump it solely on breaking changes. Ship additive, backward-compatible changes within the same major version without a new URL or header value.
• Prefer URI versioning for public APIs, header for nuance — Put a major version in the path (/v1/orders) for public, cache-friendly APIs where clients and CDNs benefit from a version visible in the URL. Use header or media-type versioning (Accept: application/vnd.acme.v2+json) when you need fine-grained negotiation and want to keep URLs stable.

Quick recipe

1. Classify the change against the breaking-vs-additive rule; only proceed to a new version if it removes/renames a field, changes a type, tightens validation, or alters default behavior. (verify: The change is documented as breaking, or shipped additively within the current version instead.)
2. Add the new major version (for example a /v2 route group or v2 media type) that reuses the shared domain and applies version-specific request/response DTOs, while /v1 keeps running unchanged. (verify: Both v1 and v2 respond correctly and share the same underlying service layer.)
3. Emit Deprecation and Sunset headers on v1 responses, publish the migration guide and removal date, and remove v1 only after the announced window closes. (verify: v1 responses carry the deprecation and sunset headers and v1 stays live until the sunset date.)

Best practices

• Treat as breaking: removing or renaming a field, tightening validation, changing a type or status code, or altering default behavior
• When retiring a version, return the Deprecation header and a Sunset header with the removal date on responses from the old version, document the migration path, and keep the old version running through the announced window
• Have clients ignore unknown response fields and not depend on field ordering, so additive server changes never break them and the API can evolve within a major version far longer

Anti-patterns

See references/anti-patterns.md.

Common mistakes

1. Making a breaking change inside the current version — Removing a field, renaming it, or tightening validation within v1 breaks live clients immediately. Fix: Ship the breaking change under a new major version, keep the old one running, and migrate clients before sunsetting it.
2. Adding a new enum value silently breaks strict clients — Introducing a new value into a response enum (a new status) can break clients that exhaustively switch on the known set. Fix: Document that enums may grow, tell clients to handle unknown values gracefully, and treat enum expansion as a signaled compatibility risk.
3. Removing an old version without a sunset window — Deleting v1 the moment v2 ships, with no deprecation period, strands clients that have not migrated. Fix: Announce deprecation, emit Deprecation/Sunset headers, and run both versions through the sunset window before removing the old one.

Version notes

• Sunset header is standardized by RFC 8594 (PHP >=8.1) — The Sunset HTTP header is defined by RFC 8594 and carries an HTTP-date; pair it with the Deprecation header (RFC 9745) so tooling can detect both the deprecated state and the removal date.

Security

• Never weaken auth or validation silently across versions — Do not loosen authentication, authorization, or input validation when introducing a new version to make migration easier, and keep security fixes applied to every supported version, not just the newest.

Testing

• Activation and decision behavior are verified in eval/scenarios/api/versioning.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: api/openapi, api/rest-design