Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 37 ยท Testing and Evolution

API Versioning and Evolving Contracts

Change a microservice API without breaking consumers: backward compatibility, the tolerant reader, expand-and-contract, schema evolution and a compatibility checker.

A service's API is a promise to every consumer. The trouble is that services must change: new features need new fields, mistakes in the first design need fixing, names get better. In a monolith you change both sides in one commit. In microservices the consumers are other teams' services, deployed on their own schedule, and you cannot update them all at once.

So evolving a contract is really about ordering: making changes in small steps where, at every moment, old and new versions of provider and consumer still work together. This lesson covers what counts as a breaking change, the rules that keep changes safe (the tolerant reader and expand-and-contract), when real version numbers are worth it, and how schema formats help. Two runnable stand-ins let you feel the difference.

Breaking and non-breaking changes

A change is backward compatible if consumers written for the old contract keep working without modification. Some changes are almost always safe; others almost always break someone.

Usually safe

Add an optional field Old consumers simply ignore it.
Add a new endpoint Nobody calls it yet.
Loosen a rule Accept more input than before.
1 / 2

A useful way to remember the rule: a provider may be liberal in what it adds but must be conservative in what it takes away. For responses, adding is safe and removing or changing is breaking. For requests, the opposite: a new field the provider requires is breaking, while accepting more is safe.

There is also a subtler category: behaviour changes. Returning results in a different order, changing an error code, or making a slow endpoint much slower never touches the schema, yet can break consumers that had quietly relied on it. Contract tests (Testing Microservices) help catch these because they encode what consumers use.

The tolerant reader

Compatibility is a two-sided effort. The tolerant reader (also called Postel's law: "be conservative in what you send, liberal in what you accept") is the consumer's half:

  • Read only the fields you need, and ignore everything else.
  • Do not fail on unknown fields, unknown enum values, or extra array items; choose a sensible default instead.
  • Use defaults for optional fields that may be missing.
  • Do not validate the whole response against a strict schema that rejects additions.

A consumer that validates "the response must have exactly these keys" turns every harmless addition into an outage. A consumer that picks its fields by name survives most evolution unchanged. The stand-in below compares both styles against the same sequence of provider responses.

JS Strict reader vs tolerant reader

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The strict reader works on day one and then fails on the harmless email field. The tolerant reader never notices. Note how it also handled the new suspended value: it mapped it to "unknown" and kept going. Deciding what "unknown" should mean for the business is still your job, but a defined fallback beats a crash.

Expand and contract

How do you rename a field when you cannot change all consumers at once? The answer is expand and contract (also called parallel change). You split one breaking change into several compatible ones.

  1. Expand

Add the new field Provider returns both name and fullName.
Keep writing the old one Nothing breaks.
1 / 3

The same pattern applies to databases (add a column, copy data, switch reads, drop the old column), to message formats, and to endpoints. The slow part is the middle: you need evidence that the old field is unused. That is why metrics on field or endpoint usage, access logs with consumer ids, and consumer contracts are valuable. Announce a deprecation with a date and, in HTTP, headers such as Deprecation and Sunset so tools can warn client teams automatically.

Versioning when you really must break

Sometimes the change is unavoidable: a different resource model, a new authentication scheme. Then you publish a new version and run old and new side by side until consumers have migrated. Common approaches:

  • URL path: /v1/orders, /v2/orders. Simple, visible, easy to route at the gateway (API Gateway and Backend for Frontend).
  • Header or media type: Accept: application/vnd.shop.order+json; version=2. Keeps URLs stable, but is harder to try in a browser.
  • Date-based versions: a consumer pins the date it integrated against and the provider applies the matching behaviour. Powerful, but needs careful engineering on the provider.

Keep versions few. Every version you keep alive costs tests, documentation and on-call attention. A healthy policy is "at most two major versions at a time, with a published sunset date for the old one". Prefer expand and contract inside a version, and use new major versions only for changes that cannot be made compatible.

Schema evolution for messages

Events live longer than HTTP calls: old events sit in a log or queue and must still be readable years later, and producers and consumers upgrade at different times. Binary formats make the rules explicit. In Protocol Buffers (RPC, gRPC and Protocol Buffers) every field has a permanent number:

PROTO
message OrderPlaced {
  string order_id = 1;
  int64  total_cents = 2;
  // field 3 used to be "currency_code"; it was removed.
  reserved 3;
  reserved "currency_code";
  string currency = 4;   // added later: old readers just skip it
}

Rules that follow from this: never reuse a field number, never change the type of an existing field, and reserve the numbers and names of removed fields so nobody reintroduces them by accident. Avro and JSON Schema have similar notions of backward (new readers read old data), forward (old readers read new data) and full compatibility; a schema registry can enforce the chosen rule when a producer tries to register a new schema, rejecting incompatible ones in CI.

A compatibility checker

The idea of a registry check is easy to run yourself. The stand-in below describes each schema as a map of fields with a type and a required flag, then compares an old and a new schema from the point of view of consumers of a response and of senders of a request. Real schema registries and tools such as OpenAPI diff cover far more cases (enums, nested objects, formats); this shows the core logic.

JS Detect breaking schema changes

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Run in CI against the last released schema, a check like this turns "I think this is safe" into a failing build before anything is deployed. It cannot catch behaviour changes, so keep consumer contract tests as well.

Treat schema files as the source of truth: generate documentation, client libraries and mock servers from them, and review changes to them like changes to code.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which change to a JSON response is normally backward compatible?

    Consumers that do not know the new field ignore it. The other changes break anyone who reads the old name or type.
  2. 2. What does a tolerant reader do?

    By depending only on what it uses, it survives additions and unknown values.
  3. 3. What is the correct order for renaming a field with expand and contract?

    Every step is compatible because old and new names exist together until nobody reads the old one.
  4. 4. Why does a Protocol Buffers message reserve the number of a removed field?

    Old data and old readers still associate that number with the old meaning, so reusing it would corrupt data silently.
  5. 5. A request schema gains a new required field. Is this safe?

    For requests the direction flips: requiring more than before breaks old callers, while accepting more is safe.

Summary

  • Adding optional fields is safe; renaming, removing, retyping or newly requiring things is breaking, and the direction (request vs response) matters.
  • Consumers should be tolerant readers: pick only what they need and handle unknown values.
  • Expand and contract turns one breaking change into several compatible releases, with metrics to show when the old form is unused.
  • Use explicit versions only for unavoidable breaks, keep few of them, and publish sunset dates.
  • Schema formats and registries make compatibility rules checkable in CI; combine them with consumer contract tests.

Next: Project: E-commerce with Orders, Payments and Stock.