API Versioning Strategies That Do Not Break Clients

Once other people depend on your API, every change can break someone. Versioning gives you room to evolve without surprises.

First: avoid breaking changes

Usually safe (additive):

• Adding a new endpoint.
• Adding an optional request field.
• Adding a field to a response.
• Adding a new value to an enum - if clients were told to handle unknown values.

Breaking:

• Removing or renaming a field or endpoint.
• Changing a field's type or meaning.
• Making an optional field required.
• Changing default behaviour or error codes clients rely on.

Strategy 1: version in the URL

GET /v1/orders
GET /v2/orders

Visible, easy to route and to test in a browser. The most common choice for public APIs.

Strategy 2: version in a header

GET /orders
Accept: application/vnd.example.v2+json

Keeps URLs stable, but is less visible and harder to try out quickly.

Strategy 3: date-based versions

GET /orders
Api-Version: 2026-06-01

Each account is pinned to the version it started with, and can upgrade when ready. Internally, small "version change" modules transform requests and responses between versions. Several large payment and SaaS APIs use this style.

Deprecating responsibly

1. Announce the timeline (months, not days) in docs and changelogs.
2. Send Deprecation and Sunset response headers on old versions.
3. Track which clients still call the old version and contact them directly.
4. Only then switch it off.