Require that changes to an API preserve backward compatibility by default, and that any deviation is a deliberate, governed decision rather than an accident of a merge. Every API must be designed so new fields, optional parameters, and additive changes never break existing consumers, and so the contract evolves without pulling the rug out from under people. I have felt the pain on both sides of a surprise breaking change, and it is one of the fastest ways to lose the trust you spent years earning. Designing for compatibility also keeps our APIs interoperable across systems, where a small incautious change can ripple far beyond the team that made it.
Compatibility (Design)
Strategies
APIs Are Interoperable Across Systems
All APIs must prioritize interoperability by using standard media types, hypermedia link relations, and well-known specifications, enabling consumers to integrate multiple APIs together and reducin...
Breaking Changes Are Prevented or Carefully Managed
All changes to APIs must be evaluated for breaking impact before release, with breaking changes requiring explicit approval, version increments, migration guides, and proactive consumer communicati...
Experiences
Interoperability
Interoperability is the experience of APIs, systems, and data working together without heroic effort. It is built on shared standards, common schema, and predictable contracts that let one system t...
Stability
Stability is the experience of being able to depend on an API not breaking underneath you. It is built on thoughtful versioning, backward compatibility, clear change communication, and honoring com...
Trust
Establish trust with API consumers will evolve and build over time, and is something that can be lost in a very short period of time. Trust will depend on other experiences like quality and reliabi...
Lifecycle
tag Versioning Define
APIs change, and how you version is how you keep faith with the people who depend on you. I decide my versioning and compatibility strategy at the beginning, not after I have already broken someone...
design_services Design Design
Design is where the human experience of an API is won or lost. I work design-first, shaping the paths, schema, errors, and naming in the contract before development begins, so that consistency is b...
