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 consumer is left stranded when APIs reach end-of-life.
APIs Are Gracefully Deprecated and Retired
Policies
Deprecation (Lifecycle)
Require that any API or operation being retired is formally deprecated first, marked in the contract, and announced with a clear sunset date and migration guidance. I treat deprecation as a promise...
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...
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...
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...
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 ...
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...
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...
