In our previous article we reviewed the different levels of visibility that you can assign to the documentation of your Healthcare API in Nubentos. But the Nubentos API Store offers access to many components and features for API consumers. It may seem that publishing your Digital Health API in Nubentos is a security or privacy problem for your resources.

Nothing further from the truth.

WHAT IS PUBLISHED IN NUBENTOS?

The first thing to clarify is that your API is not deployed outside your infrastructure. If you have your resources in an Amazon cloud, or if you have them in your own Data Center, or in any other infrastructure of your own, publishing your API in Nubentos is completely transparent.

This is also important from the legal point of view. There are countries whose legislation prohibits health processes from leaving the territory.

In Nubentos, you will only have to set up some URLs, which will also not be visible outside, and the documentation you want to include. Soon we will see that you can use the documentation tab of your API in Nubentos to “close the deal”, that is, get an anonymous visitor to subscribe to your API.

It is very likely that we have to resolve Nubentos access to your backend, so that the requests we send you from your new clients are accepted by your systems. Usually it is enough to include in our platform a mediator that adds the access credentials, tokens, keys, etc. that you generate specifically for our platform into the header of the request.

Clarified this, you may still have doubts about the publication of your API in a publicly accessible API Store, because it could be excessive exposure. 

In the next sections we will clear these doubts. We are going to see what the potential consumer of your Healthcare API in Nubentos can see and do, in each of the stages it will go through in our API Store: as an anonymous visitor, as a registered user and as a subscriber of your API.

EXAMPLE OF HEALTH API CASE: MEDICALAPI

We will use our mock test API, MedicalAPI, to illustrate this article.

We have published the API with “Public” visibility, which is the visibility level that all the APIs that are published in our API Marketplace must have.

We have also added 3 documents:

• A welcome document (“Welcome”), to which we have assigned the visibility level “Same as API visibility”.
• Another guide document (“What can you do”), to which we have assigned the same visibility level (“Same as API visibility”). This document explains some basic use cases of the API, to guide the potential consumer about the API applications. We have published it in the “How to” section of the API documentation tab.
• Another document “Agreement requirements”, which will contain detailed instructions on the requirements that the company that wants to consume the API must meet (for example, geographical area in which it will offer the product, signing of a license agreement, etc.). This document is assigned the visibility level “Visible to my Domain”, which indicates that only a user registered in my API Store can view this document.

 

With this approach, we will see what a visitor can see and do in Nubentos API Store with our API MedicalAPI.

ANONYMOUS VISITOR

When the public Nubentos API Store visitor clicks on the “Visit Publisher Store” button in the MedicalAPI API, he/she will see the private Store where the API is published.

 

Without registering or logging into this API Store, this is what you will see and can do when you click on the API:

OVERVIEW

 

The overview tab will allow you to see the production and sandbox URLs published by Nubentos (notice that these are not the URLs you provided when you published the API, which are your backend URLs), and the general description of the API that was already visible in the public API Store.

Note that the option to subscribe to the Health API does not appear anywhere.

HEALTH API CONSOLE

 

The API Console tab will allow the anonymous visitor to access the integrated test console.

The warning shown here is very important: the anonymous visitor will not be able to test the API without the corresponding Access Token in the request header (“Set Request Header”). And for this the visitor must login, and subscribe to the API.

The visitor will be able to see, without being able to use, all the resources that make up the API. That is, the methods offered by the Health API, indicating for each one the expected input parameters.

 

It is important to keep in mind that, in practice, this information is of little use without the Access Token. Of course, it poses no risk to the API provider. And it offers the visitor a very basic vision of what can be expected from that API.

To have a slightly more concrete idea of ​​the usefulness of the API, the logical thing will be to consult its documentation.

DOCUMENTATION

 

As can be seen in the image, the anonymous visitor will be able to see only documents with public visibility, that is, those that were published with visibility level “Same as API visibility”.

In this case, the welcome document and the main use cases of the Health API (which we publish in the “How to” section) are visible.

The document of requirements for the Agreement (Agreement requirements), which we added with visibility level “Visible to my Domain”, is not visible to the anonymous visitor, as we expected.

SDKs

 

The last available tab is the one that contains the 10 SDKs that the API consumer can use to integrate it into their software.

The anonymous visitor who tries to download an SDK will be taken to the registration screen. No SDK is available to the anonymous visitor. At this point, this screen is merely informative, it only shows the different SDKs available if the visitor decides to use the API.

REGISTERED USER

Suppose the anonymous visitor finds the API interesting, and wants to access more information, or wants to subscribe to see if there is an interesting consumption plan.

Then, the anonymous visitor decides to sign up.

Let’s see what has changed now by clicking on the API.

OVERVIEW

 

The first thing we see in the API overview is that now our user has access to the different subscription levels and has the option to subscribe to one of those consumption plans.

To do this an application must be selected, or use the default application, and after selecting the desired subscription tier, click on the “Subscribe” button.

In our quick guide to the API consumer in Nubentos we explain the whole process step by step.

Later we will see what happens when the user has subscribed to our API. Now let’s continue with the user who has only registered in our API Store.

HEALTH API CONSOLE

 

In the tab that gives access to our Integrated Test Console, API Console, there are few changes with respect to the anonymous visitor’s view.

If we observe, the warning message that previously told us that we must log in and subscribe to the API, now indicates that we need to subscribe to the API in order to generate the Access Token.

Let’s continue with the following tab.

DOCUMENTATION

 

In the API Documentation tab we now find access to the document “Agreement requirements”, which as you remember, we had published in our API with visibility level “Visible to my Domain”.

Since the visitor is now a user registered in our domain, that is, our API Store, documents published with that visibility level are now accessible.

In this case, as an example, we have imagined a document that informs the potential consumer about the business relationship that implies subscribing to the API and the requirements that must be met to gain access.

There are endless possibilities to make proper use of different visibility levels.

From the point of view of sales and marketing, for example you can use the anonymous visitor level to publish commercial documentation, brochures, success stories, etc., that can convince that visitor to consider a subscription.

Here, at the access level of a registered user, you can publish “Visible to my Domain” documentation that contains more detailed information, legal aspects, information about the application process and subscription approval (we’ll talk about this soon), etc.

And in a final step, with the user already subscribed and therefore become your new client, you can exchange more confidential information directly.

Nubentos helps you attract new clients, but your collaboration in the process with optimal management of your API documentation can be key.

SDKs

 

Visually there are no changes in this tab, apart from the subscription plans block that always appears for the registered user.

However, when you click on one of the available SDKs, the download of the SDK now occurs. Specifically, for the Java SDK the compressed file “MedicalAPI_1.0.0_java” is downloaded.

It is very important to be aware of what we offer your API consumer by allowing the download of an SDK.

First of all, you have to know that the SDK that is downloaded is not the same as you, as an API provider, would offer natively to your clients.

These SDKs are generated by Nubentos. They offer consumers the infrastructure of folders and files necessary to import them into their development framework. They include the code generated by our infrastructure and our Gateway to make calls to the API and receive their responses, security management and access tokens, as well as possible errors returned by our platform.

Do not forget that by publishing your API in Nubentos, we are the facade of your backend, and your new clients interact only with our platform. Only the correctly formed requests, with the correct Access Token and that comply with any other policy established in Nubentos, will be passed to your backend.

And remember that the Access Token can only be generated if there is a confirmed subscription for the user.

SUBSCRIBED USER

We move on to the next level of interest. Our anonymous visitor decided to register in your API Store to know more about your API and have the possibility to subscribe to it in order to use it.

At this point, the registered user have decided to subscribe. Let’s see what has changed now.

SUBSCRIPTION METHODS

The first thing you should know is that there are two subscription methods in Nubentos, or subscription workflows.

 

The basic workflow is active by default when a provider joins Nubentos to publish their Healthcare APIs with us. It is the most direct and the one that facilitates the fastest scalability.

For companies that want or need full control over which entity is subscribing to their API, we have enabled advanced subscription workflow.

This workflow is not active by default, so the provider that wishes to use it must request its activation.

HEALTH API CONSOLE

Whatever the method used, when a new user has subscribed to our API, the main difference is that there will be an Access Token available for Production and Sandbox environments.

 

So the user can now send requests to the API.

To do this, the user must select the Application that has generated the Access Token, and the environment to which the requests will be sent. Normally, it will be the Sandbox environment.

In our quick guide for Consumer APIs we explain the management of Applications, subscriptions and tokens.

In the rest of the API sections there are no changes for the subscribed user.

But having an Access Token now allows the users to complete the integration of the API into their software using the SDK they want, and implementing the code necessary for the use and renewal of the Token.

CONCLUSIONS

In this article we have accompanied an anonymous visitor to the Nubentos API Store, through the different stages that lead to their subscription to a Healthcare API available in Nubentos.

At each stage, we have reviewed what the user can do and cannot do, as well as what the user can see and cannot see.

DOCUMENTATION CONTROL

It is important that the API provider knows well how he can manage what documents the visitor sees who will then become a registered user, in order to become a client by subscribing to his API.

The documentation can be organized in different visibility levels, and if you activate the advanced subscription workflow, you can leave the most sensitive information for when you approve the subscription and resolve the contractual terms with your new client.

ADVANCED SUBSCRIPTION AVAILABLE

It is also important that you know that there are two subscription methods: the basic one, in which the subscription is immediate, and the advanced one, in which the subscriber is waiting for the provider to approve or reject the subscription.

This advanced workflow must be activated at the request of the provider to, in addition to controlling which entities subscribe to its API, complete the contractual or legal details that it deems appropriate with the potential client, before approving its subscription.

SDK FOR THE NUBENTOS GATEWAY

Another important detail is that in Nubentos the API provider can be calm about the visibility of its resources.

The technical resources are safe at all times, since the SDKs offered by Nubentos include only the code necessary to interact with our Gateway platform and to manage requests, responses and errors with its API.

MAXIMUM RESTRICTION FOR ACCESS TOKENS

The user cannot make any invocation, either in production or in sandbox, either from his software or in our Integrated Test Console, until the user has the corresponding Access Tokens.

Tokens are generated at the Application level and only for users subscribed to the API.

If you want to know more about the use for tokes when working with Health API in Nubentos, go to our Youtube Channel and watch the step by step and how to videos!