API-Dokumentation
API-Schlüssel
Der API-Schlüssel ermöglicht die Authentifizierung, wenn Sie Anfragen an die API stellen möchten. Die Erstellung eines API-Schlüssels, auch bekannt als Personal Access Token (PAT), ist eine sichere Methode, um sich an die Console-APIs anzumelden, ohne eine grafische Benutzeroberfläche verwenden zu müssen. Jeder dieser Tokens ist mit einem Mandanten und dem Benutzer verknüpft, der ihn erstellt hat.
Die Erstellung dieses Tokens erfolgt über Ihr Konto. Es ist möglich, mehrere Schlüssel zu generieren und für jeden die Berechtigungen entsprechend Ihren Rechten einzurichten.
Um einen API-Schlüssel zu erstellen, klicken Sie einfach auf Ihr Profil:
Im Profilmenü klicken Sie auf 'Persönlichen Zugangstoken erstellen'.
Sie sehen nun alle API-Schlüssel, die für diesen Benutzer in diesem Mandanten erstellt wurden. Klicken Sie auf 'Neuen persönlichen Zugangstoken erstellen'.
Sie müssen nun Folgendes angeben:
- Den Namen für diesen neuen Token,
- ein Ablaufdatum (maximal 12 Monate Gültigkeit),
- die zugehörigen Berechtigungen für den Token.
Anschließend werden die Details Ihres Tokens angezeigt. Achtung: Der Zugriff auf diese Informationen ist nachträglich nicht mehr möglich.
Wenn Sie diese Informationen nicht notieren, müssen Sie den Token löschen und neu erstellen.
Aus Sicherheitsgründen wird empfohlen, mehrere Tokens zu erstellen, die jeweils einer spezifischen Aufgabe dienen (z. B. ein Token pro Anwendung oder pro Geschäftsprozess), anstatt einen einzigen Token mit allen Berechtigungen zu erstellen.
Sie sehen nun den neu erstellten Token und sein zukünftiges Ablaufdatum.
Wenn Sie Ihren Personal Access Token (PAT) verwenden, um sich bei der API zu authentifizieren, erhalten Sie daraufhin einen Zugangstoken zurück. Es ist wichtig zu beachten, dass dieser Zugangstoken ein JSON Web Token (JWT) mit begrenzter Gültigkeitsdauer ist.
- Gültigkeitsdauer: Jeder JWT-Token ist 5 Minuten gültig.
- Überprüfung: Sie können Datum der Ausstellung (
iat) und Ablaufdatum (exp) Ihres Tokens überprüfen, indem Sie den Token decodieren. Online-Tools wie jwt.io ermöglichen dies einfach.
Sobald der Token abgelaufen ist, müssen Sie sich erneut mit Ihrem PAT authentifizieren, um einen neuen Token zu erhalten. Es wird daher empfohlen, diesen Lebenszyklus in Ihren Skripten und Anwendungen zu verwalten, indem Sie eine automatische Erneuerung des Tokens vorsehen.
Access to the API Portal
The OpenAPI 3.0 (Swagger) documentation for the Cloud Temple console APIs is available directly within the application:
Access to the APIs requires authentication. Once authenticated, all operations must include the header
'Authorization' with the bearer access token obtained during the authentication phase.
The URLs for the endpoints are provided directly in Swagger (in the "Servers" object on each API page).
Activities
The tracking of write-type requests (POST, PUT, PATCH, DELETE) is handled through activity management. Each such request automatically generates a corresponding activity. A HTTP status code 201 confirms the successful creation of the activity. The unique identifier of this activity is returned in the response headers under the key 'Location'.
Once the identifier has been retrieved, it is possible to access the activity details using the Activity module's API:
The activity content includes all essential information to identify the operation, its execution date, and its current progress status. Here is the model for an activity:
{
"tenantId": "UUIDV4",
"description": "STRING",
"type": "ComputeActivity" | "BackupActivity" | "IAMActivity" | "TagActivity" | "RTMSActivity" | "BastionActivity" | "SupportActivity",
"tags": "STRING[]",
"initiator": "UUIDV4",
"concernedItems": [
{
"type": "string",
"id": "string"
}
],
"id": "UUIDV4",
"creationDate": "DATE",
"operationType": "read" | "write",
"state": "CompletedState | RunningState | WaitingState | FailedState"
}
The state object can take different forms depending on the activity's status, as follows:
waiting, status before the operation has started:
waiting: {}
running, status while the operation is in progress:
running: {
status: string;
startDate: Date;
progression: number;
};
failed, status if the operation has failed:
failed: {
startDate: Date;
stopDate: Date;
reason: string;
};
completed, status if the operation has finished successfully:
completed: {
startDate: Date;
stopDate: Date;
result: string;
};
Note: The resource's UUIDv4 identifier is available in the activity result once the activity has completed.
API limits
Why limits?
The Cloud Temple console sets caps on the number of requests a user can send to the API within a given time period. Implementing these rate limits is a common practice in API management, adopted for several essential reasons:
- Prevention of abuse: These limits help safeguard the API's integrity by preventing abusive or poorly designed usage that could compromise its operation.
- Guarantee of service quality: By regulating API access, we ensure a fair distribution of resources, allowing all users to enjoy a stable and high-performing experience.
Consider a poorly designed or inefficient script making repeated API calls, risking resource exhaustion and performance degradation. By setting request thresholds, we prevent such scenarios and ensure a smooth, uninterrupted service for our entire customer base.
What are the rate limits for the Cloud Temple console API?
We apply quantitative restrictions on user interactions with the console for each product.
The limits are defined in requests per second (r/s) and per source IP. Once the threshold is exceeded, the system responds with an HTTP 429 error code, indicating that the allowed number of requests has been surpassed.
The following limits are in place:
| Product | Limit Threshold |
|---|---|
| Cloud Temple Console | 25 r/s |
| Identity (IAM) | 25 r/s |
| IaaS VMware | 25 r/s |
| OpenIaaS | 25 r/s |
| S3 | 25 r/s |
| OpenShift | 25 r/s |
| Bastion | 25 r/s |
| Networking | 25 r/s |
| Hosting | 25 r/s |
| Marketplace | 25 r/s |
| Support | 25 r/s |
| Notification | 25 r/s |
| LLMaaS | 25 r/s |
Specific Routes
Certain API endpoints, particularly those related to authentication or sensitive operations, have more restrictive limits to enhance security and ensure stability.
| Route | Limit Threshold |
|---|---|
| Authentication (IAM) | 5 r/s |
| IaaS - Storage (Datastores) | 20 r/s |
| Marketplace (Contact) | 1 r/min - 5 r/h |
How Rate Limits Work
If the number of requests sent to an API endpoint exceeds the allowed limit, the API endpoint will respond by returning
an HTTP status code 429. This code indicates that the user has exceeded the permitted number of requests.
When this occurs, the API endpoint will also provide a JSON object as part of the response,
containing detailed information about the applied rate limit:
{
"error": {
"status": "429 Too Many Requests",
"message": "Too Many Requests"
}
}
How to avoid making too many requests?
It is recommended to limit the number of API calls made by your automation to stay below the rate limit set for the endpoint.
This situation often occurs when multiple requests are executed in parallel, using several processes or threads.
There are several ways to improve the efficiency of your automation, including using caching mechanisms and implementing a retry system with exponential backoff. This method involves taking a short pause when a rate limit error is encountered, then retrying the request. If the request fails again, the pause duration is progressively increased until the request succeeds or until a maximum number of retries is reached.
This approach offers several advantages:
- Exponential backoff ensures that initial attempts are made quickly, while longer delays are scheduled in case of repeated failures.
- Adding a random variation to the pause helps prevent all retry attempts from occurring simultaneously.
It is important to note that failed requests do not affect your rate limit. However, continuously retrying a request may not be a sustainable long-term solution, as this behavior could change in the future. Therefore, we recommend not relying exclusively on this mechanism.
Python libraries Backoff and Tenacity are excellent starting points for implementing retry strategies.
API Endpoint Lifecycle
Information about the evolution of API endpoints is available in the release notes:
You will find a list of endpoints that are deprecated, organized by activity.
Additionally, deprecated endpoints will appear in our API as follows:
this/is/an/endpoint along with a definitive deletion date in the description.