API How-Tos
Overview
Using MaaS requires the use of different APIs. Most APIs support basic authentication such as username and password. The exception is the TelemetryAPI. The Telemetry API requires authentication via JSON Web Token (JWT). Authentication via JWT is supported on all APIs as well.
The following APIs must be considered when using MaaS via API. Clicking on each API LINK leads to the specification file:
API LINK | Description |
Auth API allows management of JSON Web Tokens. | |
Cloud API is optional. It is used for managing user privileges. | |
Monitoring API sets alarms & alerts and retrieves alarm history. | |
Telemetry API retrieves raw metrics of a virtual instance. This interface is compatible with Prometheus API. |
MaaS API Detailed Reference Information
Consult the sections below to learn more about each API and its relevance to MaaS.
AuthAPI
The AuthAPI is an endpoint that is used for the management of JSON Web Tokens (JWT). Any token created has a Time to Live (TTL), therefore it will expire after some time. This TTL cannot be managed by the user.
The number of tokens per identity is limited. Currently, the limit is 50. This limit is subject to change. If the limit is reached you will receive an error message indicating that no further tokens can be generated. In this event, you must delete existing tokens to create new tokens. Expired tokens will not be cleared automatically.
Initially, this API requires authentication via basic authentication (username and password) to generate the first token. Afterward, you can continue using basic authentication but you can also use JWToken to operate the AuthAPI.
If you are a reseller contract owner your account is a member of multiple contracts. Therefore, you must provide the contract number in the form of the header “X-Contract-Number” as the token must be generated in the scope of a contract.
AuthAPI documentation
Generate the first token
To generate the first token, execute the following GET call:
| Method | Request URI |
|---|---|
GET |
The response payload will contain the JWToken that can be used in other APIs. Please read the linked API documentation for further API resources as well as how to manage your token afterward.
When using JWToken, make sure to set authentication to “bearer” so that the application is aware that you will submit a JWToken and not encrypted basic authentication credentials.
CloudAPI
Using CloudAPI is optional. It is only needed if you want to grant access to the monitoring feature, especially alarms and actions, to other users who are members of your contract.
The CloudAPI supports basic authentication as well as bearer authentication via JWToken.
CloudAPI documentation
CloudAPI is available in multiple versions. The respective user management properties for granting access to monitoring are introduced in version 6 of the API. Previous versions will not allow managing the respective property.
MonitoringAPI
The MonitoringAPI is a separate service while the API endpoint is included inside the CloudAPI basepath.
The Monitoring resources do not require the versioning tag inside the URL. The MonitoringAPI supports basic authentication (username and password) as well as bearer authentication (JWT).
The MonitoringAPI allows managing (create/read/update/delete) monitoring alarms as well as actions. It contains the same properties, as mentioned above, inside the DCD description. It can be used in the same way.
MonitoringAPI documentation
TelemetryAPI
The TelemetryAPI is an API endpoint compatible with Prometheus specifications. It only supports bearer authentication (JWT). You can find Prometheus documentation below:
The TelemetryAPI allows retrieval of instance metrics. HTTP operations, other than GET, are not allowed.
Although the Prometheus specification contains many more API resources and operations, the TelemetryAPI selectively supports the following GET operations at the moment:
Last updated
