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 multiple versions are maintained during transition periods.
API Versioning Follows a Defined Standard
Policies
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.
Version of APIs
Requiring the info version property meets the policy standards.
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...
Experiences
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...
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...
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...
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...
