Protecting your API for Health is not only to implement authorization controls and access to the API, but also to properly manage the visibility of your documentation.

The general public may find it interesting to know a description of the functionality that implements the API and some criteria of service provision, such as its performance, the SLA, its main use cases or the number of companies that make use of it.

But perhaps it would be convenient if the details regarding its pricing and the subscription conditions were only available to registered users.

And finally the details on how to use the API or the technical aspects of its methods, responses, etc. should only be available to users subscribed to the API.

As we can see, there are different access levels to the documentation that we must keep in mind in our API strategy for Health. 

In this article, we will discuss each of the privileges that can be assigned to the documents that accompany the APIs published in Nubentos and the relationship they have with the visibility level of the API. 

Visibility at the API level

Let’s start by reviewing the different levels of publication that an API has.

Imagine we see a product in a store window. Next to it there is a description where we can find some of the aspects and functionalities of the product. In this case the product is exposed to the Public and that is by default the state in which we must publish our API so that all users can discover it. 

This is done by default when we are editing the API, and it is reported in the first phase of its creation.

If that information and the product is interesting, we enter the store and request more information.

If we are trustworthy, the manager will be happy to let us see the product and explain its operation, let us see its characteristics, review the warranty and its sales conditions. 

Similarly, if we have access to the space where a public API is published, we can see more detail about it, make requests from the console or access documentation that we would not otherwise see. 

But imagine that, for whatever reason, the seller does not want to expose it to the public, and only buyers who enter the store can see it and decide if they buy it.

Consider, for example, a set of APIs that work together, but one of them is the main API. It may not make sense that all of them are publicly visible, but when the customer registers in the corresponding Store, he can see the rest of the additional APIs, optional for a specific use case. 

In this case, instead of choosing that the visibility of the API is “Public” we must choose the option “Visible to my domain“. In this way a user who has not registered in its private Store will not be able to see it.

With this we have defined the two possible levels of visibility that we can choose when we publish an API. Remember that, except for very special cases, we must establish its visibility as Public. 

What is the documentation related to the publication of the API?

It is logical to think that since the documentation is associated with the API, the documentation will have the same visibility that is associated with the API when publishing it.

But the platform gives us more options. 

Each document or documentary resource can have visibility at least as restricted as that of the API. 

There are three levels of visibility for each documentary resource. 

1.- “Same as API visibility”: So if we change the API from public to restricted by domain, all the documents that have this option enabled will follow the API and keep the same visibility. It is interesting that the marketing information, features and functionalities that the entity gives to the API have this visibility associated.

2.- “Visible to my Domain”: In this case even if the API is public, only registered users will be able to access these documents. It is an ideal option for detailed technical information about the API or related to legal aspects. 

3.- “Private”: This documentation is only available for developer and consultant profiles that access the publication portal. We can add instructions for members of our team or related to the roadmap of our API, or a list of known errors so that another technician of our organization knows the peculiarities of the published API.

How do I switch between the three types of documentation visibility? 

For this, for each documentation resource that we are going to publish, we will select the appropriate one in the “Visibility” field, as shown in the following animation:

In the documentation view we can see what each of the documents visibility has, to ensure that it is correct.

In the following animation we see how documents visibility would be if the API is published as public.

In the animation we can see that, while we don’t sign in with our username and password, only a document associated with the API is shown (“Same as API visibility”), while after signing in we can access the rest of the documents (“Visible to my domain”).

Conclusions

Determining the visibility of our API’s documentary resources is as important as their content and will determine the degree of satisfaction of our potential clients.

We must make a balance between showing information that is not relevant for developers or IT managers who approach our “showcase” to see the available APIs and reserve some value-added resources for our confirmed clients, such as access to private forums or developers of our organization that can support them in the integration process.

It is very important to consistently maintain protection in accessing our API and its documentation.

In Nubentos you can manage the visibility of your API documentation with different levels, for different contents.

If you want to know more about Nubentos work processes, you will find more explanatory videos on our Youtube channel.