Versioning Service URLs with WSO2 API Manager

Question

We've recently started using the WSO2 API manager and we would like to get some clarity on the version handling aspect. There's a version number that's available by default and is mandatory.

Q1. Can we change this? Or is it a must to use this?

Q2. Should the version change only if the service signature is changing? i.e. I do a backend change to the service which causes no change to the exposed method in the web service. In this scenario do we change the version number? or only if the method changes do we change it?

Q3. Isn't it cumbersome to keep have changing the service URL of the applications? specially if the services are used for mobile applications?

Would like your insight into this and any methodology followed in a current implementation would be most welcome. Thanks!

Answer 1

Answer 1a. The format of the versioning scheme is not forced upon you, but WSO2 recommends the "version.major.minor" approach. The API versioning control may not be required, or even desired, during initial publishing, but it is likely to save some situations when a bad api needs to be revoked, or a freemium option is escalated, or a critical update needs to be made available. But IMHO, it is best practices, first.

Answer 1b. You must use a version scheme of some sort to differentiate versions of your API.

Answer 2. How you engage your versioning implementation is really based on what works best for your DevOps team. If following the version.major.minor scheme, you have a lot of flexibility in how you express changes in the formatting. Check out wikipedia's page on it[1], there is some very useful escalation examples that your users will definitely thank you for. It is really difficult for me to propose a versioning scheme without understanding your team's culture around versioning since every single team has variances in both preference and practice. I would recommend to think of the user first, though, in choosing; it is for the benefit of the end-user (app dev's) more than anything, and their frustration over a poor implementation of versioning could be the difference between usage and staleness. App developers, your users, expect versioning as much as they expect upgrades and bug-fixes. I don't believe that a service change that does not affect the API should result in an API versioning update from a purely functional perspective, but as an app developer, if you change anything, I want you to version it because I want to on-board your "perfect" changes with the ability to roll-back due to the bug that will appear even from the most perfect of teams, or to on-board the change in my own cycles and best practices. I would recommend that when you update services that don't change the functionality, release it as a minor+1 change, and offer it to users as a option to upgrade to, and allow the existing API to function unchanged (from end-to-end) by not depreciating as well as not requiring re-subscription. However, when you change a method, or fix a bug, roll it out as a version+1 or major+1, respectively, and require re-subscription to ensure clear explanation of the change and the recommended on-boarding procedures, and set a date for depreciating older outdated or faulty versions.

Answer 3. In reversing the perspective, I believe that your users are going to prefer to have an API work as subscribed to, end-to-end, and they expect to upgrade for any and all changes that happen anywhere in the service of that API. It helps with both on-boarding as well as roll-backs as mentioned, but also as a professional expectation of best practices.

In the end, it will be tremendously more cumbersome to manage upset users and bad versioning. You may also want to set a schedule of planned version changes so that your developers realize there is a good continuous improvement program in place in your shop.