Unité 1.1 : IONOS API, authentification et modèle asynchrone

Introduction

Vous êtes sur le point de créer TaskBoard, un outil de gestion de tâches API avec une interface web, et de le déployer entièrement via du code sur IONOS Cloud. Pas de clics dans le Data Center Designer. Avant de pouvoir provisionner un seul serveur, vous avez besoin de trois choses configurées correctement : la façon dont vous vous authentifiez, la façon dont le API vous indique qu'une ressource est réellement prête, et quel client (raw HTTP, SDK, ou CLI) vous utilisez dans chaque situation.

Cette unité est le contrat que vous signez avec l'outil de gestion de l'IONOS Cloud API. Le fait le plus important à retenir est que la provision est asynchrone : un POST retourne immédiatement avec un ID de demande, et non une ressource terminée. Traitez la réponse comme "acceptée, en cours de traitement" plutôt que "terminée", et vous éviterez la classe de bogues d'automatisation la plus courante sur cette plateforme. Vous configurerez l'authentification, apprendrez la boucle de polling qui contrôle chaque opération dépendante, et provisionnerez un serveur via les trois interfaces afin de pouvoir les comparer directement.

1. Le Cloud IONOS REST API

Toutes les ressources TaskBoard que vous créez, du centre de données au serveur jusqu'au Load Balancer, passent par le Cloud IONOS REST API. Le Cloud API est versionné et se trouve sous une seule URL de base. Toutes les appels CloudAPI de base ciblent https://api.ionos.com/cloudapi/v6, et les requêtes et les réponses sont JSON (Content-Type: application/json).

Les ressources sont adressées de manière hiérarchique. Un serveur, par exemple, se trouve sous son centre de données : /datacenters/{datacenterId}/servers/{serverId}. Ce regroupement est important car vous créez presque toujours un parent avant un enfant, et le parent doit être entièrement provisionné en premier (voir la Section 3).

1.1 URL de base, versionnage et types de contenu

La surface CloudAPI est fixée à v6 dans le chemin. Fixez-la explicitement dans votre code plutôt que de vous fier à un alias non versionné, afin qu'une mise à jour de version en amont ne modifie jamais silencieusement le comportement sous votre automation.

# Smoke-test connectivity and auth: list your datacenters
curl -s -X GET 'https://api.ionos.com/cloudapi/v6/datacenters?depth=1' \
  -H 'Authorization: Bearer '"$IONOS_TOKEN" \
  -H 'Content-Type: application/json'

Le paramètre de requête depth contrôle la quantité de l'arbre de ressources imbriquées qui est retourné. depth=1 retourne la collection avec les propriétés de niveau supérieur ; des profondeurs plus élevées intègrent les enfants. Gardez depth faible sur les appels de liste pour réduire la taille de la charge utile, et demandez une ressource spécifique par ID lorsque vous avez besoin de détails complets.

1.2 Remarque sur les hôtes API séparés

Non tous les services IONOS se trouvent sous cloudapi/v6. Certains services exposent leurs propres hôtes (par exemple, IAM Federation utilise https://iam.ionos.com, et le CDN utilise un hôte régional). Lorsque vous intégrez ces services dans les modules ultérieurs, lisez le point de terminaison à partir de la documentation de ce service plutôt que de supposer la base CloudAPI. Le header d'authentification, cependant, reste le même jeton porteur à travers ces hôtes.

2. Authentification

L'IONOS Cloud API accepte deux méthodes d'authentification : un jeton porteur (la méthode principale et recommandée) et l'authentification de base en utilisant votre nom d'utilisateur et votre mot de passe de compte.

Deux faits opérationnels déterminent le choix. Premièrement, les comptes avec 2FA activé ou imposé doivent utiliser l'authentification par jeton porteur. Deuxièmement, l'authentification de base est documentée comme étant interrompue dans un avenir proche et ne doit être utilisée qu'en combinaison avec 2FA. La conclusion pratique pour toute nouvelle automatisation : utilisez des jetons porteurs.

2.1 Jetons porteurs via le Token Manager

Vous générez des jetons via l'authentification Token Manager de API/SDK (dans le DCD sous Menu > Gestion > Token Manager, via le API, ou via la CLI). Un jeton est une chaîne que vous placez dans l'en-tête Authorization de chaque demande.

# Bearer token on every CloudAPI request
curl -s -X GET 'https://api.ionos.com/cloudapi/v6/datacenters' \
  -H 'Authorization: Bearer '"$IONOS_TOKEN"

Vous pouvez demander un jeton de manière programmatique à partir du point de terminaison de génération de jetons, puis réutiliser cette valeur de jeton pour les appels API et SDK suivants :

# Generate a token using Basic auth, then switch to the token for all later calls
TOKEN=$(curl -s -u "$IONOS_USERNAME:$IONOS_PASSWORD" \
  -X GET 'https://api.ionos.com/auth/v1/tokens/generate' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])')

export IONOS_TOKEN="$TOKEN"

Notez que l'hôte de génération de jetons est auth/v1, et non cloudapi/v6. Le jeton que vous obtenez est ensuite utilisé contre le CloudAPI.

2.2 Cycle de vie du jeton : création, étendue et rotation

Le Token Manager impose des limites concrètes que vous devez concevoir. Vous pouvez générer jusqu'à 100 jetons d'authentification par utilisateur, et chaque jeton a une durée de vie (TTL) choisie lors de la création parmi un ensemble fixe d'options : 1 heure, 4 heures, 1 jour, 7 jours, 30 jours, 60 jours, 90 jours, 180 jours et 365 jours.

La valeur du jeton est affichée exactement une fois lors de la génération et n'est pas récupérable par la suite ; vous pouvez également le télécharger sous forme de fichier à ce moment-là. Capturez-le immédiatement dans votre magasin de secrets, car il n'y a pas de « montrer à nouveau » plus tard.

Ces limites déterminent un modèle de moindre privilège et de rotation convivial. Émettez un jeton séparé à TTL court par service et par environnement (un pour le pipeline CI de TaskBoard, un pour le service API en cours d'exécution, etc.) plutôt que de partager un jeton à longue durée de vie partout. Puisque les jetons expirent sur une durée de vie fixe, la rotation est une routine que vous automatiserez plutôt qu'un exercice de lutte contre les incendies.

# Read the token from the environment, never hardcode it
import os

IONOS_TOKEN = os.environ["IONOS_TOKEN"]  # fails loudly if unset
# Hardcoding a 365-day token in source is the fastest way to leak credentials.

Le plafond de 100 jetons signifie qu'un script défectueux qui frappe un nouveau jeton par exécution épuisera votre quota. Frappez une fois, stockez, réutilisez jusqu'à l'expiration, puis faites pivoter.

3. Le modèle de provisionnement asynchrone

C'est la règle qui casse plus d'automatisations IONOS que toute autre : les opérations de provisionnement sont asynchrones. Un POST ou un PUT ne retourne pas une ressource terminée. Il retourne 202 Accepted, la nouvelle ressource entre dans un état BUSY, et un Location pointe vers une URL d'état que vous interrogez jusqu'à ce que le provisionnement soit terminé.

Vous devez attendre la fin du provisionnement avant toute opération qui dépend de la nouvelle ressource. Attacher un Volume à un serveur qui est encore BUSY, ou créer une carte réseau sur un centre de données à moitié provisionné, échoue. Le modèle asynchrone n'est pas optionnel, et il n'est pas quelque chose que vous pouvez contourner avec des réessais sur l'appel dépendant seul.

3.1 La réponse 202 et l'en-tête Location

Lorsque vous créez une ressource, le statut de la réponse est 202 Accepted, le corps contient la nouvelle ressource id, et l'en-tête de la réponse comprend une URL d'état à interroger.

# Create a datacenter; capture the request status URL from the Location header
curl -s -D - -o /tmp/dc.json \
  -X POST 'https://api.ionos.com/cloudapi/v6/datacenters' \
  -H 'Authorization: Bearer '"$IONOS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"properties":{"name":"taskboard-dc","location":"de/fra"}}' \
  | grep -i '^location:'

Le header Location contient l'URL de l'état de la requête. Le modèle est identique pour tous les types de ressources : la documentation des points de terminaison Cloud API indique que la réponse comprend un header Location avec un URL pour interroger l'état de la requête, et la ressource conserve un état BUSY jusqu'à ce que la mise en service soit terminée.

3.2 Interrogation jusqu'à DONE

Le point de terminaison d'état signale l'état de la requête. Vous l'interrogerez jusqu'à ce que l'état soit DONE (une mise en service échouée apparaît comme FAILED). Ce n'est qu'alors que vous procédez aux opérations dépendantes.

La forme exacte de la charge utile de l'état de la requête et le rythme d'interrogation recommandé ci-dessous reflètent une pratique d'automatisation IONOS courante plutôt qu'un extrait de documentation verbatim. Les valeurs d'état BUSY, DONE, et FAILED sont basées sur la documentation ; la structure de la boucle est une mise en œuvre standard.

# Poll the status URL until the request reports DONE
STATUS_URL="https://api.ionos.com/cloudapi/v6/requests/<request-id>/status"

until [ "$(curl -s -H "Authorization: Bearer $IONOS_TOKEN" "$STATUS_URL" \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["metadata"]["status"])')" = "DONE" ]; do
  echo "still provisioning..."
  sleep 5
done
echo "resource ready"

Les SDK encapsulent cette boucle pour vous. Passez l'option SDK qui attend la completion et le client interroge internalement, de sorte que votre code d'application se lit comme si l'appel était synchrone tout en respectant le modèle asynchrone sous-jacent.

4. SDK et l'interface CLI ionosctl

Vous n'écrirez pas de code brut curl pour la logique d'application. IONOS publie des SDK pour Python (ionoscloud), Go (sdk-go), Java et JavaScript, ainsi que l'outil de ligne de commande ionosctl. Tous authentifient avec le même jeton porteur et tous doivent respecter le modèle asynchrone.

4.1 Le SDK Python

Le SDK Python utilise un objet Configuration (contenant votre jeton) enveloppé dans un ApiClient, que vous remettez ensuite aux classes API spécifiques au service.

Les noms de classe et de méthode SDK ci-dessous (Configuration, ApiClient, DataCentersApi, ServersApi, et la méthode datacenters_servers_post) reflètent l'interface publiée du SDK Python ionoscloud à partir de connaissances générales ; vérifiez les signatures exactes contre la version SDK que vous avez épinglée.

import os
import ionoscloud
from ionoscloud.api import data_centers_api, servers_api
from ionoscloud.models import Server, ServerProperties

config = ionoscloud.Configuration(token=os.environ["IONOS_TOKEN"])

with ionoscloud.ApiClient(config) as api_client:
    servers = servers_api.ServersApi(api_client)
    server = Server(properties=ServerProperties(
        name="taskboard-api",
        cores=4,
        ram=8192,            # MB; 8 GB
        cpu_family="INTEL_SKYLAKE",
    ))
    # The SDK can wait for the async request to finish for you
    created = servers.datacenters_servers_post(
        datacenter_id=os.environ["TASKBOARD_DC_ID"],
        server=server,
    )
    print("server id:", created.id)

Le SDK lit votre jeton à partir de l'objet Configuration. Gardez la durée de vie de cet objet liée à la durée de vie du jeton et actualisez-le lors de la rotation.

4.2 L'interface de ligne de commande ionosctl

ionosctl est l'interface la plus rapide pour les tâches ponctuelles, la scripting et l'inspection. Authentifiez-vous une fois, puis exécutez des commandes.

La syntaxe de la commande ionosctl ci-dessous reflète la structure de commande publiée de l'outil à partir de connaissances générales ; confirmez les indicateurs contre votre version de ligne de commande installée avec ionosctl <command> --help.

# Authenticate the CLI with a token
ionosctl login --token "$IONOS_TOKEN"

# List datacenters
ionosctl datacenter list

# Create a server (ionosctl waits for the request by default)
ionosctl server create \
  --datacenter-id "$TASKBOARD_DC_ID" \
  --name taskboard-api --cores 4 --ram 8192

4.3 Choix d'une interface

Le tableau suivant compare les quatre façons dont vous interagissez avec l'IONOS Cloud API afin que vous puissiez choisir délibérément plutôt que par habitude.

Comme indiqué ci-dessus, utilisez le SDK pour la logique d'application, ionosctl pour les tâches rapides et le collage de CI, le HTTP brut lorsque vous déboguez le protocole lui-même, et Terraform (prochaine unité) pour tout ce qui devrait exister en tant qu'état déclaratif.

5. Limitation de débit, pagination et gestion des erreurs

L'automatisation de la production rencontre trois réalités que les exemples de chemin heureux omettent : le API vous limite le débit, les collections sont paginées, et certains codes d'erreur signifient quelque chose de différent de ce que vous attendez.

5.1 Limitation de débit avec recul exponentiel

Lorsque vous dépassez le taux de requête, le API répond avec 429. La réponse correcte consiste à reculer de manière exponentielle et à réessayer, plutôt que de solliciter sans cesse le point de terminaison.

La mise en œuvre de l'exp-backoff ci-dessous est un modèle de réessai standard côté client ; la sémantique de statut 429 est ancrée dans la documentation, les délais et les perturbations spécifiques sont un choix d'implémentation.

import time, random, requests

def get_with_backoff(url, headers, max_retries=6):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)
        if resp.status_code != 429:
            resp.raise_for_status()
            return resp
        # Honor Retry-After if present, else exponential backoff with jitter
        wait = int(resp.headers.get("Retry-After", 2 ** attempt))
        time.sleep(wait + random.uniform(0, 1))
    raise RuntimeError("rate limit: retries exhausted")

5.2 Pagination avec décalage et limite

Les points de terminaison de liste renvoient des collections paginées contrôlées par offset et limit. Le paramètre limit limite le nombre d'éléments par page, et offset définit le point de départ dans la collection. Sur les points de terminaison de collection, la valeur par défaut limit est 1000 et la valeur par défaut offset est 0.

# Iterate every page of a collection
def list_all(url, headers, page_size=1000):
    offset, items = 0, []
    while True:
        page = get_with_backoff(
            f"{url}?offset={offset}&limit={page_size}", headers
        ).json()
        batch = page.get("items", [])
        items.extend(batch)
        if len(batch) < page_size:
            break
        offset += page_size
    return items

Ne supposez jamais qu'un seul appel a retourné tout. Si vous avez obtenu exactement limit éléments, il y a presque certainement une autre page.

5.3 Gestion des erreurs et le piège 404

L'erreur que vous lirez incorrectement en premier lieu est 404 lors de la mise en service. Un 404 immédiatement après la création d'une ressource signifie généralement que la ressource n'est pas encore prête, et non qu'elle manque. C'est le modèle asynchrone qui vous mord : vous avez sauté le sondage et interrogé une ressource enfant avant que son parent n'ait atteint DONE.

# WRONG: create then immediately use -> intermittent 404
created = servers.datacenters_servers_post(datacenter_id=dc_id, server=server)
volumes.datacenters_volumes_post(datacenter_id=dc_id, volume=vol)  # may 404

# RIGHT: wait for DONE, then proceed (SDK wait option, or poll the status URL)

Lisez les corps de réponse en cas d'échec. Les réponses d'erreur IONOS incluent une charge utile structurée avec le code HTTP et un message lisible par l'homme ; enregistrez-le plutôt que de supprimer l'exception, afin qu'un 429, un corps malformé (422), et un échec d'authentification (401) soient immédiatement reconnaissables dans la sortie de votre pipeline.

API Référence Quick Card

Points de terminaison clés API pour l'authentification et le modèle asynchrone :

URL de base : https://api.ionos.com/cloudapi/v6 Hôte de jeton : https://api.ionos.com/auth/v1 Authentification : Authorization: Bearer <token>

Laboratoire de code

Objectif : Provisionner un serveur de trois manières différentes (curl, Python SDK, ionosctl) et vérifier l'achèvement asynchrone à chaque fois.

Prérequis :

• Compte IONOS Cloud avec accès API
• curl, python3, et ionosctl installés localement
• Le ionoscloud Python SDK : pip install ionoscloud

Étape 1 : Générer et exporter un jeton

export IONOS_TOKEN=$(curl -s -u "$IONOS_USERNAME:$IONOS_PASSWORD" \
  -X GET 'https://api.ionos.com/auth/v1/tokens/generate' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["token"])')

Sortie attendue :

(no output; verify with: echo ${IONOS_TOKEN:0:8}...)

Étape 2 : Créer un centre de données et capturer l'URL de statut de la demande

curl -s -D /tmp/hdr -o /tmp/dc.json \
  -X POST 'https://api.ionos.com/cloudapi/v6/datacenters' \
  -H "Authorization: Bearer $IONOS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"properties":{"name":"taskboard-dc","location":"de/fra"}}'
grep -i '^location:' /tmp/hdr
export DC_ID=$(python3 -c 'import json;print(json.load(open("/tmp/dc.json"))["id"])')

Sortie attendue :

location: https://api.ionos.com/cloudapi/v6/requests/<id>/status

Étape 3 : Interroger jusqu'à ce que le centre de données soit terminé

STATUS=$(grep -i '^location:' /tmp/hdr | awk '{print $2}' | tr -d '\r')
until [ "$(curl -s -H "Authorization: Bearer $IONOS_TOKEN" "$STATUS" \
  | python3 -c 'import sys,json;print(json.load(sys.stdin)["metadata"]["status"])')" = "DONE" ]; do sleep 5; done
echo done

Sortie attendue :

done

Étape 4 : Créer un serveur via curl

curl -s -X POST "https://api.ionos.com/cloudapi/v6/datacenters/$DC_ID/servers" \
  -H "Authorization: Bearer $IONOS_TOKEN" -H 'Content-Type: application/json' \
  -d '{"properties":{"name":"srv-curl","cores":2,"ram":4096,"cpuFamily":"INTEL_SKYLAKE"}}'

Sortie attendue :

{"id":"<server-id>","type":"server", ... }

Étape 5 : Créer un serveur via le Python SDK

import os, ionoscloud
from ionoscloud.api import servers_api
from ionoscloud.models import Server, ServerProperties
cfg = ionoscloud.Configuration(token=os.environ["IONOS_TOKEN"])
with ionoscloud.ApiClient(cfg) as c:
    s = servers_api.ServersApi(c).datacenters_servers_post(
        datacenter_id=os.environ["DC_ID"],
        server=Server(properties=ServerProperties(
            name="srv-sdk", cores=2, ram=4096, cpu_family="INTEL_SKYLAKE")))
    print("sdk server:", s.id)

Sortie attendue :

sdk server: <server-id>

Étape 6 : Créer un serveur via ionosctl

ionosctl login --token "$IONOS_TOKEN"
ionosctl server create --datacenter-id "$DC_ID" --name srv-cli --cores 2 --ram 4096

Sortie attendue :

ServerId   Name      Cores   Ram     State
<id>       srv-cli   2       4096    BUSY -> AVAILABLE

Étape 7 : Répertorier tous les serveurs et confirmer qu'il en existe trois

ionosctl server list --datacenter-id "$DC_ID"

Sortie attendue :

srv-curl, srv-sdk, srv-cli all AVAILABLE

Liste de validation :

• [ ] Jeton généré et exporté, jamais codé en dur
• [ ] Le centre de données a atteint DONE avant qu'un serveur ne soit créé
• [ ] Trois serveurs créés via trois interfaces différentes
• [ ] Les trois serveurs atteignent l'état AVAILABLE

Nettoyage :

# Deleting the datacenter removes its child servers; avoids ongoing charges
ionosctl datacenter delete --datacenter-id "$DC_ID" --force

Pièges courants

1. Traiter la mise en service comme une opération synchrone

   • Problème : Votre script crée un serveur et attache immédiatement un Volume, ce qui entraîne une erreur intermittente 404 ou une erreur de conflit.
   • Pourquoi cela se produit-il : Le POST renvoyé 202 Accepted avec la ressource dans l'état BUSY ; la ressource n'est pas encore prête.
   • Correction : Interroger l'URL d'état à partir de l'en-tête Location jusqu'à DONE, ou utiliser l'option d'attente de la fin de l'exécution du SDK, avant toute appel dépendant.

2. Créer un jeton frais à chaque exécution

   • Problème : Un travail planifié cesse de fonctionner après un certain temps avec des erreurs d'authentification, et vous trouvez des dizaines de jetons dans le Token Manager.
   • Pourquoi cela se produit-il : Chaque utilisateur est limité à 100 jetons ; un script qui génère un jeton par exécution épuise la quote-part et perd la trace de quel jeton est actif.
   • Correction : Générer un jeton étendu par service/environnement, le stocker dans un magasin de secrets, le réutiliser jusqu'à l'expiration de sa durée de vie, puis le faire pivoter. La valeur du jeton n'est affichée qu'une seule fois, il faut donc la capturer lors de sa création.

3. Lire seulement la première page d'une collection

   • Problème : Une opération de liste omet silencieusement les ressources au-delà des 1000 premiers éléments.
   • Pourquoi cela se produit-il : Les points de terminaison de collection paginent avec un limit par défaut de 1000 ; le code qui ignore offset/limit voit une seule page.
   • Correction : Boucler avec un offset croissant jusqu'à ce qu'une page renvoie moins de limit éléments (voir la section 5.2).

Résumé

Vous détenez maintenant le contrat sur lequel repose chaque unité ultérieure. Vous pouvez vous authentifier avec un jeton porteur à partir de l'Token Manager, respecter le modèle de provisionnement asynchrone en interrogeant requests/{id}/status jusqu'à DONE, et provisionner la même ressource via curl, le Python SDK, et ionosctl. Vous pouvez également maintenir l'automatisation en vie sous charge en faisant marche arrière sur 429 et en parcourant de grandes collections. Avec cette fondation, les travaux d'infrastructure de TaskBoard dans l'unité 1.2 deviennent une question d'expression de ces mêmes opérations de manière déclarative dans l'Terraform.

Points clés :

• L'URL de base de CloudAPI est https://api.ionos.com/cloudapi/v6 ; les jetons sont générés à https://api.ionos.com/auth/v1/tokens/generate.
• Le provisionnement est asynchrone : POST retourne 202 Accepted, la ressource devient BUSY, et vous interrogez l'URL de statut Location jusqu'à DONE avant les opérations dépendantes.
• Utilisez des jetons porteurs (l'authentification de base est en cours de suppression et les comptes 2FA doivent utiliser des jetons porteurs) ; un utilisateur peut détenir jusqu'à 100 jetons, chacun avec une durée de vie fixe allant de 1 heure à 365 jours.
• La valeur d'un jeton est affichée exactement une fois et n'est pas recoverable, vous devez donc la capturer lors de sa création ; vous pouvez la télécharger sous forme de fichier à ce moment-là.
• Un 404 juste après la création signifie généralement "pas encore prêt", et non "manquant" ; gérer 429 avec un recul exponentiel et pagez les collections avec offset/limit (limite par défaut 1000).

Terminologie importante :

• Jeton porteur : Une credenciale de chaîne délivrée par l'Token Manager, envoyée dans l'en-tête Authorization: Bearer, et la méthode d'authentification principale pour l'IONOS Cloud API.
• Modèle de provisionnement asynchrone : Le comportement de la plateforme où les appels de création/mise à jour retournent 202 et une URL de statut Location ; la ressource est BUSY jusqu'à ce que le provisionnement atteigne DONE.
• Point de terminaison de statut de la demande : /cloudapi/v6/requests/{id}/status, interrogé pour savoir si une opération asynchrone est BUSY, DONE, ou FAILED.
• Durée de vie du jeton : La durée de vie fixe choisie lors de la création du jeton (1 heure à 365 jours) qui détermine votre calendrier de rotation.
• Pagination (décalage/limite) : Paramètres des points de terminaison de collection où limit limite les éléments par page (limite par défaut 1000) et offset définit l'index de départ.

Prochaines étapes

Continuer l'apprentissage : Unité 1.2 : Terraform Provider et modèles de base

Sujets connexes :

• Unité 1.2 : Terraform Provider et modèles de base
• Unité 1.3 : Vérification des connaissances - Fondements programmatiques