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. Thoughtful versioning is the difference between an API consumers trust and one they are afraid to build on.
Versioning
Define
Stop 3
Policies at this stop
Created Date for APIs.json Contracts
Providing the data in which an API contract was created, establishing the inception of a specific contract involving one or more APIs, which defines the age of the contract.
Modified Date for APIs.json Contracts
Providing the data in which an API contract was last modified, tracking the change that occurs with each API contract, understanding the velocity as well as stagnation of APIs.
Change Log Version
The version of the change that was made to an API.
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...
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...
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 ...
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...
Version of APIs
Requiring the info version property meets the policy standards.
OpenAPI Version
Requiring there is the latest version of OpenAPI available.
Version
The version of the proposed API change in the road map.
Road Map
Providing a simple yet informative look at what features are being planned for future releases of an API, or even sharing that nothing is currently being planned--just providing any insight on what...
Date-Based Versioning
Require usage of date-base versioning for managing change.
Semantic Versioning
Require usage of major, minor, and patch Semantic Versioning for managing change.
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 ...
