api-versioning-strategy

Put an integer version in the URI path (e.g., /v2/orders), require it on every request, and never change existing fields in place. Ship changes as expand (add new field), migrate (move traffic with telemetry), then contract (remove old field) in separate deploys.

Yes, in practice. Clients with exhaustive switch statements and no default branch will crash on the unknown value. Either document from day one that enums are open and clients must tolerate unknowns, or introduce the new state in a new API version.

URI path versioning is the recommended default. It is copy-pasteable into bug reports, greppable in access logs, trivially routable at gateways, and cached correctly without a Vary header. Header-based content negotiation is purist but painful in practice.

Plan roughly 12 months from announcement to sunset for public APIs, versus about 3 months for internal ones. Send Deprecation and Sunset headers on every response, run scheduled brownouts returning 410 Gone, and track per-client usage metrics before cutoff.

A rename has no rollback: the moment it ships, in-flight requests from old clients fail on the missing key, and rolling back does not undo client-side errors already surfaced. Expand-migrate-contract across separate releases is the safe alternative.