What is the "Manager" API and how should I (not) use it?

The API called "Manager" is an API made available by Sensedia for our customers to apply settings related to API design-time via HTTP calls.

To understand this better, it’s worth having in mind a simplified diagram of the API Platform:

The gateway receives and handles calls from apps and sends the calls to the correct servers. Then, it receives the responses from the servers and sends them to each respective app. The whole process of receiving and answering calls is part of the API runtime and takes place in what we call the data plane.

At runtime, the gateway applies a series of settings that are established by the user at the API design-time, which occurs in what we call the control plane. In our case, these settings are established on the API Manager, which is the graphical interface responsible for Platform control.

In other words, on the API Manager the user defines how the gateway will behave. For example, it’s through the Manager that we define that a certain API will only accept access tokens generated by the OAuth Authorization Code flow and that another API will have a limit of calls per minute. These settings are sent to the gateway, which applies them at runtime.

The "Manager" API is nothing more than an API that we provide so that control-plane configurations can be done by HTTP calls instead of exclusively through the API Manager GUI. This is very useful when you want to configure the Platform by CLI or when you want to implement CI/CD automations in API design-time processes.

The separation between the two spheres of the Platform (the control plane and the data plane) is essential for the whole ecosystem to be stable and scalable. Therefore, it’s important that the "Manager" API is only used as a design-time aid tool.

This means that you should never include calls to the "Manager" API as part of the production flow of another API. If you did that, you would overlap the control plane and the data plane and probably cause instability in your APIs (with the risk of lost calls due to timeout or high latency, for example).