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 communication, minimizing disruption to existing integrations.
Breaking Changes Are Prevented or Carefully Managed
Policies
Breaking Changes (Lifecycle)
Require that breaking changes to a production API are identified, avoided where possible, and never shipped silently onto an existing version. I hold this line hard because a breaking change you di...
Change Management (Lifecycle)
Require that every change to a production API moves through a defined change management process that assesses impact, tracks dependencies, and communicates what is changing before it lands. I want ...
Compatibility (Design)
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 s...
Robustness (Design)
Require that APIs are designed for robustness on both sides of the wire, being conservative in what they send and tolerant in what they accept, so that small variations do not cascade into outages....
Versioning
Providing semantic or date-based versioning for an API, offering an overview of what is adopted for an API and why, letting consumers know that their is change management in place and how they can ...
Semantic Versioning
Require usage of major, minor, and patch Semantic Versioning for managing change.
Date-Based Versioning
Require usage of date-base versioning for managing change.
Migration Guides (Experience)
Require that whenever an API version is deprecated or a breaking change is introduced, a clear migration guide is published that shows consumers exactly how to move from the old to the new. I insis...
Change Log
Having a change log of anything added, updated, or removed for an API, but also for the other operational and supporting resources for each API, ensuring there is a easy to read manifest of what ha...
Experiences
Alignment
Achieving alignment between teams producing APIs and their consumers is a persistent challenge in API operations. Effective collaboration between business and technical stakeholders requires ongoin...
Change
Managing and effectively communicating changes across one or more APIs is a leading cause of instability and friction in enterprise operations. While these changes often surface in applications use...
Communication
Consistent communication about the production and consumption of APIs is critical for effective enterprise governance. APIs are inherently difficult to visualize, making it essential to invest in m...
Consistency
Achieving consistency in the design, delivery, and maintenance of HTTP APIs across an enterprise is a significant challenge—one that often complicates API operations. Small differences, such as var...
Reliability
If an API isn’t reliable, consumers will eventually look for alternatives. Reliability starts with the platform and infrastructure where the API is deployed, but it also depends heavily on the pace...
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...
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...
Governance
Governance is the experience of keeping API operations consistent and aligned as they scale across teams and time. It is the discipline that connects strategy at the top to the rules being enforced...
