Which API versioning strategy is best?

URL path versioning (/v1/users) is the most practical choice for most teams. It is visible in logs, easy to test with curl and browsers, simple to route at the load balancer level, and unambiguous in documentation. Header-based versioning produces cleaner URLs but adds testing complexity. Date-based versioning (like Stripe) works well for APIs with frequent incremental changes but requires more sophisticated routing logic. Choose one strategy and apply it consistently across all endpoints.

What counts as a breaking change in a REST API?

Breaking changes include: removing or renaming a response field, changing a field data type (string to integer), making a previously optional request parameter required, changing URL structure, altering endpoint behavior or semantics, changing error response format, and modifying authentication requirements. Non-breaking changes include: adding new response fields (clients should ignore unknowns), adding optional request parameters, adding new endpoints, and relaxing validation constraints.

How long should I support a deprecated API version?

Industry standard is 6 to 12 months from deprecation announcement to removal. Set the timeline based on your client ecosystem: internal APIs can move faster, public APIs with paying customers need longer. Communicate the timeline via Sunset and Deprecation HTTP headers on every response, email notifications to registered developers, and your API changelog. Monitor usage of deprecated versions and proactively reach out to clients who have not migrated as the sunset date approaches.

How do I handle requests to a removed API version?

Return HTTP 410 Gone with a response body that includes the sunset date, a link to the current API version, and a link to the migration guide. Some APIs redirect with 301 Moved Permanently to the equivalent endpoint in the current version, but this can break clients if the request and response formats differ between versions. A 410 response is clearer because it tells the client the resource is intentionally removed and will not return.

How does Stripe approach API versioning?

Stripe uses date-based versioning where each API key is pinned to the API version current at key creation time. Clients opt into newer versions by setting the Stripe-Version header. Each version change includes a detailed changelog showing exactly which fields changed. This approach avoids URL clutter and lets Stripe make frequent small changes without major version bumps. The trade-off is more complex server-side routing logic that must support many concurrent versions.

Versioning APIs Without Breaking Clients