Connected infrastructure

Plan a compatible interface change

Editorial edition · 16 November 2026

The idea

An interface change is compatible only relative to the clients that use it. Adding a field can still break a strict parser, and adding an enum value can break an exhaustive switch. Compatibility needs evidence about real client behaviour.

Design choice

Separate additive changes from changes in meaning, defaults or validation. Test representative old clients against the proposed response. If a new version is necessary, give the old one a documented support window and track remaining callers before retirement.

Worked example

A reporting endpoint adds a nullable explanation field. A contract test reveals that one importer rejects unknown keys. The team updates that importer before enabling the field for all clients.

Before you ship

  • Test an older client.
  • Check semantic changes as well as field shapes.
  • Assign an owner to the retirement decision.

Examples are illustrative. Adapt the checks to your own environment.

Further reading

HTTP Semantics, RFC 9110

Search the library