API Versioning Strategies: URL Path, Header Negotiation, and Zero-Downtime Deprecation

Every evolving software system will eventually need to deprecate outdated workflows or restructure core schemas. The difference between smooth evolution and developer outrage lies in having a structured versioning and deprecation governance policy.

URL Path Versioning vs Content Negotiation

While theoretical REST purists advocate for content negotiation via the Accept header (e.g., application/vnd.company.v2+json), real-world developer experience overwhelmingly favors explicit major versioning in the URL path (e.g., /v1/orders to /v2/orders). URL path versioning simplifies CDN routing, proxy rules, and manual testing in API clients like Postman and Insomnia.

The Additive Evolution Rule

Before jumping to a new major version, apply the rule of non-breaking additive evolution:

• Never remove a field from a response schema without an announced deprecation sunset window.
• Never change the data type of an existing field (e.g., string to integer).
• Add optional fields rather than making existing optional fields required.
• Maintain backwards-compatible default values for newly introduced request parameters.

Sunset Headers & Deprecation Alerts

When deprecating an endpoint, utilize RFC 8594 Sunset and Deprecation response headers. These inform automated monitoring clients of the scheduled sunset timestamp, allowing partner teams to plan migrations well ahead of final decommissioning.