May 19th, 2016 by Adam Sandman
As we're wrapping up the final testing of SpiraTeam v5.0 we're adding the documentation and testing the new v5.0 API. This API will be available in both REST and SOAP options. This reminds us of why we're adamant about the need to version the API and not resist the impulse to make changes to existing functions and methods. This article explains discusses API versioning and some suggestions we have for anyone thinking of adding an API to their product.
You Cannot Predict the Future
There is a temptation to try and forecast the future and try and write an API that will contain all of the future functionality you might possibly need, define some kind of glorious open standard of an API that will define all your needs in the future. This would be great, it means your users could write to this API now knowing that it will handle all their future needs!
Well if we'd done that 15 years ago we'd have it nicely written in CORBA, it would have 10,000 functions and it would be unusable by anyone!!
The reality is that with an Agile approach you are adding functionality and user stories progressively, from a Minimum Viable Product (MVP) to Release 2.0, to Release X. The API needs evolve as your product does. For example, early versions of our API were written in SOAP and supported just 10 custom properties (since that all SpiraTeam could handle).
Fast forward 10 years and we have SOAP and REST APIs, we support JSONP, CORS and other protocols needed for modern web applications. We could never have predicted that.
One early "mistake" we made in our v1.0 API was to send back internal data structures (ADO.NET DataSets serialized as XML) through are API. That was a problem, since in v1.2 we had to change some of our database fields and that broke the API for all clients. We decided from that day forward, each API version would have its own Model, with its own objects and properties. That way an "Incident" object in v3.0 of the API could have a different signature than an "Incident" in v5.0 of the API. We still use this approach today.
You Cannot Change the Past
Similarly you won't have time to rewrite every plugin and integration you have written, nor will you be able to control what third-party developers are using your API for (if you are successful!). So our policy has always been, when we publish an API for a version of Spira, we don't change it in a way that will break older clients, we'll wait until the next version of the API is released before we add the functionality.
This means that we have some plugins (e.g. PyUnit plugin) written 7 years ago against Spira v2.2 that still work today. Imagine if we had to back over all of the old plugins every time we released a new version of Spira. It would mean that we'd spend months just to get everything working again. When you consider that many of the plugins are written using different languages (.NET, Java, Ruby, JS, Python, Perl) it would be a very time consuming task, especially when you have test them.
To ensure the old APIs still work the same way, we build translation layers in the API that convert the new database in Spira to the format expected by the old versions. Sometimes this can get tricky (e.g. when we added 20 more custom properties or when we added release and requirement types) but we try and make it as seamless as possible. We also have a set of automated NUnit unit tests written specifically for each version to make sure they work as previously expected.
Sometimes You Need to Say No (or Wait!)
Finally sometimes you have to say No to your customers (or at least wait a bit). For example many customers have asked us to add Components and Requirement Types to our v4.0 API so that users of Spira v4.2 could access them in other tools (e.g JIRA). However we know that would break the v4.0 API, so we politely said No and instead it will now be part of the completely expanded v5.0...