If you're an API provider, or you're thinking about becoming an API provider, the video below might be one of the best videos you'll ever watch when it comes to versioning your APIs over the course of their lifecycles. In some ways it parts with conventional wisdom when it comes to API versioning. But, occasionally, breakthrough thinking like this has a way of changing everyone's perspective on API lifecycle management.
API versioning and retirement is one of the eight phases of API lifecycle management that ProgrammableWeb pays close attention to. In fact, over the course of 2016, we've been shifting the data model behind our API directory to better accomodate the availability of concurrent versions of an API. Now, based on the content of this video, we're glad we did because it not only confirms that it's OK to have multiple versions (and microversions within them) of an API in production, it goes into a lot of detail about how to make it work well for both the API provider and the consuming developer. Additionally, it gives us here at ProgrammableWeb some new ideas about some steps we can take when it comes to the future of our data model.
The video is a recording of a presentation given by NetApp software engineer Clinton Knight and HP Enterprise software engineer Scott D'Angelo at this year's OpenStack conference in Barcelona. The basic idea behind API microversioning is that even the slightest change to an API would constitute a new microversion number. In the video, the presenters routinely refer to version 2 of an API whose microversions span 2.0 to 2.22. All microversions are kept in production simultaneously, there's one endpoint that services all of them, and the consuming developer specifies which microversion s/he prefers using a field in the HTTP header (what they call a "magic header field"). Additionally, a secondary "versions API" runs sidecar to the primary API -- one that can be interrogated by the developer in order to figure out things like what is the API's current version, what is the range of supported microversions (ie: 2.0 to 2.22), and what other primary versions (ie: 1.0) are still supported.
Another benefit of such a microversion approach to versioning APIs (and using an HTTP header field to specify which microversion to work with) is that it also makes it easier to offer pre-release, beta, or experimental releases of a microversion. The experimental release might get a microversion number like 2.23. But as long as it is an experimental release, the only way for a developer to access it is to include a special HTTP header field (ie: “-H “X-OpenStack-Manila-API-Experimental”) with the request that indicates the developer is deliberately and knowingly accessing an experimental release. According to the presenters, it's an "explicit acknowledgement that you know what you're doing and that the API can change without being subject to the deprecation rules."
The approach also handles certain contingencies that might otherwise result in an error. For example, what happens when the magic header field doesn't accompany an API call (it defaults to the earliest microversion which is considered to also be the most compatible) or what happens when the magic header field includes an invalid microversion (this results in a 404). In fact, even if the request includes a valid microversion number, the response echoes that microversion number as a confirmation that it understood and processed the request accordingly. If the developer interrogates the sidecar "versions" API and feeds the wrong version in the HTTP header, the versions API will not 404. Rather, it will still respond with a range of valid microversions (ie: 2.0 to 2.22).
One challenge that arises when new thinking like this starts to become a part of the API fabric is that the various API management and design solutions do not explicitly support such an approach. If the idea catches on, you can expect those solutions to catch on. But for now, those solutions will lack the equivalent of an "easy button" that makes child's play of microversioning. Here's the video.