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:
Consult the sections below to learn more about each API and its relevance to MaaS.
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
To generate the first token, execute the following GET call:
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.
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.
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
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:
| Method | Request URI |
|---|---|
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.
GET
Grafana is an open source platform for data visualization, monitoring and analysis. You may integrate this software with the Monitoring as a Service for more convenient use.
Go to the API reference
Install grafana
Generate the first token
curl -uusername:password https://api.ionos.com/auth/v1/tokens/generate or -n if you use netrc
It is also possible to query the metrics using curl:
curl -H "Authorization: Bearer ${TOKEN}" https://api.ionos.com/telemetry/api/v1/query?query=instance_cpu_utilization_average
Login to Grafana
Configuration (on the left side)
Data source
URL: https://api.ionos.com/telemetry/
Custom HTTP Headers
Header: Authorization Value: Bearer eyJ0eXAiOiJK....
HTTP Method: POST
Save & Test
Go to Explore (on the left side)
Choose the new Data source
In the Metrics Browser, write instance
Choose one of the metrics
Run query
You can query on these metrics now:
series whitelist:
- instance_cpu_utilization_average
- instance_network_in_packets
- instance_network_out_bytes
- instance_network_in_bytes
- instance_network_out_packets
- instance_volumes_read_bytes
- instance_volumes_write_bytes
- instance_volumes_read_ops
- instance_volumes_write_ops
