If you, as an API provider, have already followed the steps to publish your Health API in Nubentos, the most exciting moment is just around the corner: the first consumers of your API will soon arrive. But what should you know about the management of subscriptions, accesses and versions of the API to have total control of its use? We’ll discuss these important topics in this post.

Access control for your Health API

The Nubentos platform provides a large amount of information and possibilities to manage the consumption made by your customers. Let’s review the main aspects.

By signing in to the API Publisher platform with the consulting profile, you can go directly to the Health API detail screen and see the API overview information.

 

The first thing you can see is that your API is already published. It already has two subscribed users.

Now you can go to the “Users” tab to see what use they are making of the API.

 

As you can see, for each of those two users, you can see on what date they have registered and what use they are making of the API. You have this information that close.

Subscription control

If for any reason we are forced to block a user’s access to your API, you have two possibilities.

The first is to block access to the production environment by leaving the sandbox environment available for testing.

The second is to block access to all environments completely. 

To do this, in the menu on the left, select the “MANAGE SUBSCRIPTIONS” option, which will show you the list of users subscribed to the API. By selecting the subscriber in the drop-down menu, you can block access.

 

Similarly, you can enable access when you deem necessary.

From the point of view of the applications that make use of the API, while the subscription is blocked, the requests they make will receive the following response:

 

 

The blocking of requests to the gateway is done in real time, but you must keep in mind that it takes some time to spread to all gateway nodes, and that the expiration time of the caches has to be met (a maximum of 15 minutes).

To terminate all user access permissions with the consumer profile, it is necessary to contact Nubentos support.

Control from the API Lifecycle

The subscriptions of your API will also be affected by certain changes in the API life cycle. If an API goes to BLOCKED status, subscriptions will be suspended. Upon making a request they will receive the following response:

 

 

Another special case that occurs when we manage the life cycle of an API, is that all users subscribed to an API of a given version will automatically be subscribed to the new version, unless you indicate otherwise in the publishing process. Developers have to make the necessary changes to use to the endpoints of the new version.

 

In this screenshot you can see how all subscribers have been cloned into the new version of the API.

How to manage versions of a Health API? 

One of the most important aspects that you have to take into account when you manage an API in “Production” being consumed, is how to publish a new version of your API.

You must notify all consumers of the previous version that you have made available a new version, and redirect them to the API documentation so that they can see its roadmap.

This way they will know when the current version will be removed, which means that all consumers should be using the new version by then.

To promote a new version of the published API after the development team has made the changes, you must access the Nubentos API Publisher with the consulting profile.

Two icons will appear with the different versions of the API. 

You can see that the currently published API is version “1.0.0” and that it has two subscribed users, while the new version “1.0.1” is still in “CREATED” state and has no subscribers.

Click on the detail of the version 1.0.1 and then on the “Lifecycle” tab. 

You will see two checks that influence how subscriptions are transferred from the version 1.0.0 of your API to the new version to be published. 

The first one is “Deprecate old version after publish the API”, and implies that all users subscribed to version 1.0.0 will lose their subscription and the API of that version will not be available anymore.

The second check is “Requires re-subscription when publish the API”, which will force all subscribers of version 1.0.0 to have to re-subscribe to the new version.

If you do not mark any of these checks and click on the “PUBLISH” button, the new version of the API will be published and it will have two new subscriptions with the same users as the previous version.

 

You have to take into account that each API has a different endpoint since the version is part of the endpoint URL.

 

From the consumers point of view, in the list of subscriptions associated with their application, a different one will appear for each version of the API.

 

It is up to the consumer users to deactivate the subscription (Unsubscribe) with the previous version when their application has been adapted to the new version.

In a future article we will show you the steps that you must follow to remove the old version of an API, and what precautions you should take to avoid affecting the applications that are consuming your Health API.