API specification versioning against API releases,How is API specification versioning best done?

Not applicable

@Dom Couldwell has provided a great best practice page that specifically mentions using collaborative environments for specifying APIs. I am wondering how we manage multiple API releases against specification versions. For example, as I plan to add new features to a given API, I will update the spec (in Confluence in our case). At the same time others might be developing an older API release, but the spec has now been updated. Our specs spans several Confluence pages, so I'm wondering if there's a best practice / simple way for spec'ing APIs and relating them to specific API releases.

Thanks

1 1 492
1 REPLY 1

dcouldwell
Participant III

My general advice is to think of the only two incarnations of your API Spec as 'As is' and 'To be'.
The 'As Is' release of your API will be reflected in your API Consumer facing documentation i.e. what you push out the in the Developer Portal.

The 'To Be' release of your API is reflected in your in flight API Specification e.g. in Confluence that includes the 'To Be' release of your API Consumer facing documentation and also all the info your API Developers need to build the next release of your API.

A key recommendation on making your program successful is short release cycles where once an API is developed it's in production asap with minimal cycling after development is complete. If you take that premise forwards it means that you should not have a long gap between release 1.1 of your API being dev complete before it's in production so even if you're starting on release 1.2 the 1.1 'To Be' incarnation of your API has become the 'As is' release.

Main point I'm trying to make is that you should try to avoid having to maintain 2 'in flight / To Be' releases of the API. If you really need to keep a track of what was the spec for r1.1 vs r1.2 and if you're using Confluence each page does have a version history or you could choose to extract all the pages for a given release of an API into a pdf doc.