Md Nayeem Hossain | Software Engineer

API Versioning and Backward Compatibility Without the Pain#

The moment an API has a client you do not control — a mobile app that users do not update, a partner integration, a public developer platform — every change becomes a negotiation. Break something, and integrations fail silently in someone else's production system.

The best versioning strategy is the one you rarely need, because most changes are designed to be backward compatible. This post covers both.

What counts as a breaking change#

A change is breaking if a correctly written existing client stops working:

Removing or renaming a field, endpoint or query parameter.
Changing a field's type or format (a number becomes a string, a date format changes).
Making an optional request field required.
Adding a new required validation rule.
Changing error codes or HTTP status codes that clients rely on.
Changing default behavior, such as sort order or pagination size.

These changes are usually non-breaking:

Adding a new endpoint.
Adding an optional request parameter.
Adding a new field to a response.

That last one assumes clients ignore unknown fields. Write that expectation into your API documentation — the "tolerant reader" principle — so clients do not break when you add data.

Evolve instead of versioning#

Most needs for a new version disappear if you evolve carefully:

Rename by adding. Instead of renaming name to fullName, add fullName, keep returning name, mark it deprecated, and remove it only once no client uses it.

Widen, do not narrow. Accept more input formats rather than fewer.

Use enums defensively. If a field may gain new values, tell clients to handle unknown values gracefully from the start:

json

1{2  "status": "paid",3  "statusNote": "Clients must treat unknown status values as 'processing'."4}

Make new behavior opt-in through a parameter or header rather than changing the default.

When you do need a version#

Sometimes a resource model is fundamentally wrong and must change. Then you need a real version. The common approaches:

URL versioning#

http

1GET /v2/campaigns/123

Explicit, easy to route, easy to see in logs and documentation. It is my default for most APIs.

Header versioning#

http

1GET /campaigns/1232Accept: application/vnd.affsflow.v2+json

Keeps URLs stable and resource-oriented, but is less visible and harder to test in a browser.

Date-based versioning#

Some large API providers pin each client to the API version that was current when they integrated, identified by a date, and transform responses between versions internally. It is excellent for developer experience and significant engineering work, best suited to large public platforms.

Implementing versions without duplicating everything#

Running v1 and v2 should not mean two copies of your business logic. Keep one core implementation and translate at the edges:

1@Controller("v1/campaigns")2export class CampaignsV1Controller {3  constructor(private readonly campaigns: CampaignService) {}4 5  @Get(":id")6  async get(@Param("id") id: string) {7    const campaign = await this.campaigns.get(id);8    return toV1(campaign); // map the current model to the old response shape9  }10}

The domain model moves forward. Old versions become thin adapters that are easy to delete later.

Deprecation is a process#

Removing an old version is where most teams struggle. Make deprecation explicit and measurable:

Announce the deprecation with a timeline in the changelog and to known integrators.
Signal it in responses, using Deprecation and Sunset headers so clients can detect it automatically.
Measure usage per version and per client. You cannot remove what you cannot see.
Contact remaining users directly as the sunset date approaches.
Remove the version, ideally with a brief brownout first — returning errors for an hour — to flush out forgotten integrations safely.

http

1Deprecation: true2Sunset: Wed, 01 Jul 2026 00:00:00 GMT3Link: <https://docs.example.com/migrate-to-v2>; rel="deprecation"

Catch breaking changes automatically#

Humans miss breaking changes in review. Generate an OpenAPI spec from your code and compare it against the previous release in CI. Tools can flag removed fields, changed types and new required parameters before they are merged.

Conclusion#

Design for evolution first: additive changes, tolerant readers, deprecated fields instead of renamed ones. When a real break is unavoidable, version explicitly, keep one core implementation with thin adapters, and run deprecation as a measured, communicated process. Your clients will trust your API, and your team will not be stuck maintaining five versions forever.