Path versioning or Accept header—what should we pick?

If your API is public or cache-heavy, choose path versioning (`/v1`). If you control clients (mobile/web SDKs) and want smoother evolution without URL churn, use media types (`Accept: application/vnd.acme.v2+json`). Don’t mix styles within the same surface area.

When do we bump the major version?

Only when you need to remove, rename, or repurpose fields; change types; or alter semantics that break tolerant readers. Additive changes (new optional fields, endpoints, query params) should not bump major.

How do we do this with GraphQL?

Don’t version the endpoint. Use `@deprecated` on fields/enum values, add new types/fields, and communicate removal timelines. Provide query examples and codemods in client repos.

Use proto3 with additive fields; never change field numbers or types. Mark removed fields as `reserved`. For optional semantics, use wrapper types like `google.protobuf.*Value`.

Guides · Oct 25, 2025 · 10 minute read

Stop Breaking Clients: A Field‑Tested API Versioning Playbook That Actually Preserves Backward Compatibility

I’ve seen more outages from “harmless” API tweaks than from full rewrites. Here’s the pragmatic versioning strategy we deploy at clients to ship changes without lighting up PagerDuty.

Back to all posts

Stop Breaking Clients: A Field‑Tested API Versioning Playbook That Actually Preserves Backward Compatibility

Key takeaways

Implementation checklist