API Evangelist API Evangelist
API Learnings
APIs
API Governance
API Solutions
API Discovery
API Building Blocks
API Evangelist LLC

Change - Versioning

Secondary

Communicating the versioning strategy behind APIs is a useful way to align both API producers and consumers when it comes to API change. Versioning is all about managing and communicating change, and a date-based or Semantic Versioning approach can be used to align everyone involved. Dates uses time to communicate change, and Semantic Versioning uses a major, minor, and patch format to communicate the scope and velocity of change.

Having a dedicated versioning page provides another useful property of an API contract that contributes to the overall stack of change manage solutions on the table. Communicating a versioning strategy will inform API consumers, but also forces API producers to establish and stick to a plan for how change will occur. With opting to not version being one of the valid approaches to managing change when delivering an API.

Versioning APIs is not easy and gets more complex over time and across the number of APIs being delivered. Not versioning requires more communication and more API design discipline. When it comes to versioning there are many ways to approach, but it is something that is difficult to over communicate, so make sure and publish your strategy for anyone to read in a self-service way.