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 commitments over time. Consumers build businesses on top of APIs, and stability is what makes that a reasonable thing to do. I value stability because trust in an API is earned slowly and lost instantly. A single unannounced breaking change can undo years of goodwill and send consumers looking for alternatives. The providers who treat stability as a promise, and communicate clearly when things must change, are the ones consumers stay loyal to.
Stability
Policies
API Exit and Migration Path
Require that an API documents a clear path for consumers to migrate onto, between, or off of it without being stranded. Lock-in by design erodes trust, so an honest operation makes leaving possible...
Deprecation Sunset Headers
Every deprecated API operation must announce itself in-band using Deprecation and Sunset headers that tell consumers a change is coming and when it lands. I require that deprecation be signaled thr...
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....
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 ...
Retirement (Lifecycle)
Require that retiring an API is a deliberate, documented step that only happens after a deprecation period, with the shutdown date, the reason, and the alternative all made clear to consumers. I wa...
Strategies
API Dependencies Are Tracked and Managed
All API-to-API dependencies must be documented and tracked, with upstream and downstream impact analysis performed before changes are made, ensuring that teams understand the ripple effects of chan...
API Versioning Follows a Defined Standard
All APIs must follow a defined versioning strategy, whether semantic versioning or date-based versioning, with clear policies for how versions are communicated, how consumers are migrated, and how ...
APIs Are Gracefully Deprecated and Retired
All APIs must follow a formal deprecation and retirement process that provides consumers with adequate notice, migration support, and a clear timeline from deprecation to removal, ensuring that no ...
APIs Earn and Maintain Consumer Trust
All APIs must demonstrate trustworthiness through transparent service level commitments, consistent deprecation policies, reliable performance, proper security, and clear legal terms, building the ...
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...
