Versioning & Evolving APIs Without Breaking Clients

In one line

APIs live longer than the code behind them. Evolve them with additive, backward-compatible changes; when you must break, version explicitly, run both versions, and retire the old one with deprecation notices and data.

0/7 · 0%

Think of it like this

A train timetable. You can ADD a new train without confusing anyone. But if you rename a station, every printed ticket and every regular commuter is lost. Renames need a long transition with both names on the signs.

Key ideas

01
SAFE (additive) changes: new endpoints, new optional request fields, new response fields (clients must IGNORE unknown fields: the 'tolerant reader' rule). BREAKING changes: removing or renaming fields, changing types or meanings, making an optional field required, changing error codes, tightening validation.
02
VERSIONING options: in the PATH (/v1/orders, visible and simple, the most common for public APIs), in a HEADER (Accept: application/vnd.shop.v2+json or API-Version: 2026-09-01, cleaner URLs, as in Stripe's date-based versions), or in a query parameter. Pick one and apply it consistently.
03
DEPRECATION process: announce, add Deprecation and Sunset headers with a date, measure who still calls the old version (per-client metrics and API keys make this possible), contact them, and only then remove it. Mobile apps make this slow, because old app versions stay installed for years.
04
CONTRACT TESTS (e.g. Pact, or schema diffs of the OpenAPI spec in CI) catch breaking changes before they merge. For events on Kafka, the same rules apply through a schema registry (Phase 10).

Explain without notes

Why must clients ignore unknown fields?

Practice

You need to change price (a number in rupees) to a money object {amount, currency}. Plan the rollout without breaking the mobile app.

Trade-offs

↔
Path versions are explicit but encourage big-bang rewrites; date-based header versions allow fine-grained evolution but need more infrastructure (version transformers) on the server.

Run it in production

You've designed it. Now build, operate, and break the same idea hands-on in the DevOps courses:

Stateful · Kafka replication, retention & operations

ISR, min.insync.replicas, compaction, schemas, and Strimzi.

GitOps · Deployment strategies with Argo Rollouts

Canary, blue-green, and automated analysis.

Completion checklist

I can classify a change as additive or breaking
I have a deprecation process with headers and usage metrics

Back to phase