The “how” of the lifecycle – Digital Transformation with IBM API Connect

As you develop new, and update existing, APIs and add them to your products, they must be published to make them visible to consumers to subscribe to and invoke. By now, you should already know how to stage and publish your product, which is what you would do for the initial version. Once you start introducing subsequent versions, your process will change.

Let’s take an example of an API named Member API, which is contained within the Member product in our example health care organization. We have developed, staged, and published version 1.0.0 of this product to our Production Catalog. It is now time to create a new version of this API and product.

To create a new version of this API, you will follow the following steps:

  1. Navigate to the Develop APIs and products screen in API Manager and make sure you are on the APIs tab. From here, you will locate your current version of your API.
  2. Click the ellipsis on the far right of that row, and select Save as New Version. Figure 11.2 shows us creating a new version of our Member API.

Figure 11.2 – Save as New Version

3. As you are prompted for the new version, you will enter the next version number and click on Submit. In our Member API example, we created a new 1.0.1 version. You can now see this in Figure 11.3:

Figure 11.3 – Version 1.0.1 created

4. Once you have your new version created, you can modify it with the required changes.

5. Once your changes are complete, you will need a new version of your product as well since that is what our consumers will subscribe to. You can follow the same procedure that we followed for creating a new version of your API for the product.

You will notice that when you create a new version of your product from the current version, the current API also comes along with it. You will need to remove this version from the product and add the new version. This is accomplished by navigating to the API and product development page, going to the Products tab, and clicking the product and version you want to edit. Once you have selected the product and version you want to work with, you will click the API’s link on the left of the page. You will see that the new version of your product has the previous version of the API still in it. Clicking the Edit button will then bring you to a screen where you can unselect the old version of the API and select the newer version of the API as shown in Figure 11.4. Once these changes are made, clicking Save will complete the change.

Figure 11.4 – Select a new version of the API within the product

You now have a new version of your API and product that is ready to stage. As you have done before, you can now stage this version of your product to the appropriate Catalog. As with all of your APIs and products, be sure to download and add this to your source control management system.

At this point, you should have a current, published version of your product and a staged version of your newest version. You could just go ahead and publish your staged version and then deprecate your current version in two separate steps but you do have a simpler option available. If you navigate to the Catalog where you have your products, you should see each version of the product and its current state. In our Member API product example, we have a published Member version 1.0.0, and a staged Member product version 1.0.1 in our Production Catalog. At the far right of each product row, you can click the ellipsis of your published product and see all of the available options, including three that can be used to change the state of the product, which are Deprecate, Retire, and Supersede. You will also see a Replace option but that technology will not change the current state. Figure 11.5 shows these options for our published Member product version 1.0.0:

Figure 11.5 – Product options from within the Catalog

The Deprecate and Retire options should be self-explanatory but the option we are interested in here is the Supersede option. This is the one option that we can use to publish our staged version and deprecate our current version because that is exactly what this option does. It will publish the chosen superseding product, giving it the same visibility options as the superseded product. It will then deprecate the superseded product. Once a product is superseded, all current subscribers can continue to consume the APIs within the product, however, no new subscribers will be allowed. Although this is a convenient, one-click option to publish one version and deprecate the current version, it should not be used if your new version’s interface has major changes as it could have a negative impact on your existing consumers.

If you go ahead and click the Supersede option for your published version of the product, you will then be asked to select which version of the product you want to supersede this version. Again, the version selected will become the published version and the version to supersede will become deprecated. Figure 11.6 shows us selecting version 1.0.1 of our Member product to supersede our published version 1.0.0:

Figure 11.6 – Superseding Member product 1.0.0

Clicking the Next button will then bring you to a screen showing the superseded and the superseding products. From this screen, you will also select which plans you will want to migrate to the superseding product. In Figure 11.7, you can see that we selected the default-plan that was used in our superseded version to migrate:

Figure 11.7 – Select plans to migrate to superseding product

Clicking on the Supersede button from this screen will complete your supersede operation. You will be brought back to the Catalog page showing all of the current products where you started. You will need to click the refresh icon to see the products reflecting their new states, as shown in Figure 11.8, where our Member 1.0.0 product is in a deprecated state and our Member 1.0.1 product is now published:

Figure 11.8 – Member products after superseding

You can continue to use this option each time a new version of your API and product comes out, but your list of deprecated products will just keep growing. Eventually, you will need to remove some of the older versions. You can do this by using the Retire option you saw earlier in the product options from within your Catalog. As a good housekeeping rule, you should only keep one API in each state. Before retiring a product version, you should make sure that all consumers subscribed to that version of the product are notified as this version will no longer be accessible.

To retire a version of your product, you would simply select the Retire option next to the product in the Catalog screen as shown in Figure 11.9.

Figure 11.9 – Retire a product version

You will then be shown a confirmation screen where you will confirm that you want to retire this product. Once the product is retired, all subscriptions to it become inactive and it is removed from the developer portal.

In Figure 11.9, note the options available for the product version that is currently in a deprecated state. From this state, you can also choose to republish this product if you wish.

As you can see, the products in a retired state will still show in your Catalog within API Manager so you must again stay diligent and delete them when you are sure that they are no longer needed. This is the final stage in the API and product lifecycle. Once you delete a product, it is removed from only the Catalog. The product and APIs within it still exist, however they are no longer part of a Catalog. If this product was again needed, you would need to re-stage it to the Catalog and start the lifecycle over again.

In this section, we demonstrated the API lifecycle showing the APIs and products moving freely with a simple click of an option to bring them to the next state. In a development environment, this may be the most efficient way to migrate from state to state as there will likely be many changes to a particular API throughout the development process.

As you move through higher environments such as quality assurance (QA) and production, you will most likely not allow a developer to move an API and product through the different states without approvals. This is why you have the ability to require approvals at each stage of the lifecycle. In the next section, we will discuss this process.

Related Post

Leave a Reply

Your email address will not be published. Required fields are marked *