API Life Cycles with WSO2 API Manager

One of the key API management challenges that we're trying to address in WSO2 API Manager is governing the API life cycle. Once you have developed, tested and published an API, you need to maintain it. Time to time you will roll out newer versions of the API into production with bug fixes, functional improvements and performance enhancements. When a new version is rolled out, you need to deprecate previously published versions thereby encouraging the subscribers to use the latest stable version of the API. However you will have to keep supporting the old versions for a period of time, thus providing existing subscribers some concession time to migrate to the latest version. But at some point you will completely take the old API versions off production and retire them from service. At a glance all this looks very simple and straightforward. But when you add the usual DevOps overhead into the picture, managing the API life cycle becomes one of the most complicated, long running tasks that you need deal with. If this long term procedure isn't tedious enough, there are many short term maintenance activities you have to do on APIs which are already in production. More often than not, you would want to temporarily block the active APIs so the system administrators can perform the required maintenance work on them. A well thought out API life cycle design should take these long term as well as short term requirements into consideration.

We at WSO2 gave this problem a long, hard thought and came up with the following schematic which illustrates the major life cycle states of a typical API.

If you download the beta release of WSO2 API Manager, you will see how we have incorporated the above model into the product design. Not only the product supports different life cycle states, it makes it absolutely simple to switch between different states. It's quite fascinating to see how API Publisher, API Store and API Gateway adjust to the changes in perfect synchronism as you take an API through its complete life cycle. In general these are the semantics that we have enforced for each life cycle state.

• Created – A new API has been created and awaiting moderation. It hasn't been published to the API Store yet and hence cannot be consumed.
• Published – API has been moderated and published to the API Store and is available to subscribers. Subscribers can use them in applications, generate keys against them and consume them.
• Deprecated – API has been marked for retirement in near future. New subscriptions are not allowed on the API, but the existing subscriptions and keys will continue to work. However the existing subscribers are highly advised to upgrade to the latest version of the API.
• Blocked – The API has been temporarily disabled for maintenance.
• Retired – The API has been permanently taken off service.

Lets try some of this stuff out and see for ourselves. Extract the downloaded WSO2 API Manager Beta pack, go into the “bin” directory and start the server up. Launch your web browser and enter the URL https://localhost:9443/publisher. Login to the portal using the default admin credentials (user: admin, pass: admin). Go ahead and create a new API. You can create the “FindTweets” API described in one of previous posts.

Note that the API is initially in the “CREATED” state. While in this state, the API is not visible in the API Store. Point your web browser to http://localhost:9763/store to confirm this. Now go back to the API Publisher portal and click on the “FindTweets” API. Select the “Life Cycle” tab which contains the necessary controls to change the API life cycle state. 

To start with put the API into the “PUBLISHED” state and click “Update”. Go to the API Store and refresh the page. The “FindTweets” API should now be visible there. 

You can login to the API Store, click on it and subscribe to the API using the “DefaultApplication”. When done your “My Subscriptions” page will look something like the following.

Go ahead and generate a production key too. Using this you can invoke the “FindTweets” API. Refer to my previous “Hello World” post if you're not sure how to invoke an API.

Now go back to API Publisher and change the API state to “BLOCKED”. If you immediately come back to the “My Subscriptions” page and refresh it, you will see that the “FindTweets” API is displayed as a “Blocked” API.

Any attempts to invoke this API will result in a HTTP 503 response.

Go back to the API Publisher and change the API state back to “PUBLISHED”. Try to invoke the API again, and you will notice that things are back to normal. Now in the API Publisher, go to the “Overview” tab of the “FindTweets” API and click on the “Copy” button.

Enter a new version number (eg: 2.0.0) to create a new version of the “FindTweets” API. The newly created version will be initially in the “CREATED” state and hence will not show up in API Store. However the API Publisher will list both versions of the API.

Now go to the “Life Cycle” tab of “FindTweets-2.0.0” and select the “PUBLISHED” state from the drop down. This time, since your API has some older versions, you will get some additional options to check.

Make sure all the provided options are checked. Checking the “Deprecate Old Versions” option ensures that all the older versions of the “FindTweets” API will be put into the “DEPRECATED” state as you roll out the new version into API Store. Checking the “Require Re-Subscription” option makes sure that existing subscribers will have to re-subscribe to the new version of the API in order to consume it. That is the keys generated against the old version of the API will not be forward compatible with the new version of the API. Having checked all the options, click the “Update” button to apply the changes. If you go back and check your “My Subscriptions” page you will notice that the API has been marked as “Deprecated”.

However, if you go to the API Store home page you will notice that the old version of “FindTweets” is no longer listed there. Only the latest published version is listed on this page.

Even if you somehow manage to access the “FindTweets-1.0.0” API details page on API Store (may be via the link available in “My Subscriptions” page), you will notice that you are no longer given any options for subscribing to the API. In other words, no new subscriptions are allowed on the deprecated APIs.

However if you try to invoke the old version of the API, using the previously obtained key, you will notice that it continues to function as usual.

And now finally, go back to the API Publisher and put the “FindTweets 1.0.0” API to the “RETIRED” state. Check the “My Subscriptions” page after the change.

Also try invoking the API with the old key. You will get a HTTP 404 back as the API has been undeployed from the system.

I hope this post gave you a brief introduction to how API governance and API life cycle management works in WSO2 API Manager. You can try various other options available in the product such as leaving the “Require Re-Subscription” option unchecked when publishing a new version of the API. See how that will automatically subscribe old subscribers to the new version of the API. See the extent to which API meta data is copied when creating a new version of the API using the “Copy” option. Send us your feedback to dev@wso2.org or architecture@wso2.org.