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 tune into communication.
Versioning
Rules
APIs.json Apis Properties Versioning Info
This property ensures there is a reference to how APIs are versioned, giving a single place where teams can learn about how change is communicated
Strategies
API Change is Managed Relative to Operational Change
I keep running into teams that manage change for each API like it exists in its own little universe, completely disconnected from the bigger operational picture. That never works. You need a shared...
APIs Are Gracefully Deprecated and Retired
How you shut down an API says as much about your operations as how you launch one. I have seen too many teams just flip the switch and leave consumers stranded. You need adequate notice, migration ...
Breaking Changes Are Prevented or Carefully Managed
Breaking changes are the fastest way to destroy trust with your API consumers. Every change needs to be evaluated for breaking impact before it ships, and when breaking changes are unavoidable, the...
API Versioning Follows a Defined Standard
Versioning is where the technology and politics of API operations collide. Semantic versioning, date-based versioning--pick a strategy and stick with it. What matters most is that consumers know ho...
Experiences
Alignment
I see product and engineering teams talking past each other constantly when it comes to APIs. Without alignment on the why behind each API, you end up with technically sound resources that nobody a...
Change
Change is the one constant across the API landscape, and I watch teams struggle with it every single day. If you aren't actively managing and communicating change across versions, deprecations, and...
Communication
I struggle with how little communication happens between the teams producing APIs and the people consuming them. Blogs, changelogs, roadmaps -- these are building blocks that most teams just skip, ...
Consistency
When I look across the API landscape, consistency is one of the biggest challenges I see. Every team does things differently, and the surface area of inconsistency just grows until governance becom...
Quality
I see the quality of APIs eroding across the landscape. Teams ship fast and never look back, but consumers feel every rough edge, every missing example, every inconsistent response. Quality is what...
Reliability
Reliability is where the rubber meets the road in the API landscape. If your APIs aren't up when consumers need them, and if new versions don't land smoothly, none of the other building blocks matter.