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

Introduction

Vous allez construire TaskBoard, une API de gestion de tâches avec une interface web, et déployer chaque composant via du code sur IONOS CLOUD. Aucune interaction avec l'interface de Data Center Designer. Avant de pouvoir provisionner le moindre serveur, vous avez besoin de trois éléments correctement configurés : la méthode d'authentification, la manière dont l'API vous indique qu'une ressource est réellement prête, et le client (HTTP brut, SDK ou CLI) à utiliser dans chaque situation.

Cette unité constitue le contrat que vous signez avec l'API IONOS CLOUD. Le fait le plus important à assimiler est que le provisionnement est asynchrone : un POST renvoie immédiatement un identifiant de requête, et non une ressource terminée. Considérez la réponse comme « accepté, en cours de traitement » plutôt que « terminé », et vous éviterez la catégorie la plus courante de bugs d'automatisation sur cette plateforme. Vous configurerez l'authentification, apprendrez la boucle de sondage qui conditionne chaque opération dépendante, et provisionnerez un serveur via les trois interfaces afin de pouvoir les comparer directement.

1. L'API REST IONOS CLOUD

Chaque ressource TaskBoard que vous créez, du datacenter au serveur en passant par l'équilibreur de charge, passe par l'API REST IONOS CLOUD. L'API Cloud est versionnée et réside sous une URL de base unique. Tous les appels principaux de CloudAPI ciblent https://api.ionos.com/cloudapi/v6, et les requêtes et les réponses sont au format JSON (Content-Type: application/json).

Les ressources sont adressées de manière hiérarchique. Un serveur, par exemple, réside sous son datacenter : /datacenters/{datacenterId}/servers/{serverId}. Cette imbrication est importante, car vous créez presque toujours un parent avant un enfant, et le parent doit être entièrement provisionné d'abord (voir la section 3).

1.1 URL de base, versionnage et types de contenu

La surface de 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 à niveau de version en amont ne modifie jamais silencieusement le comportement sous votre automatisation.

# 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 profondeur de l'arborescence des ressources imbriquées qui est renvoyée. depth=1 renvoie la collection avec les propriétés de premier niveau ; des profondeurs supérieures incluent les enfants en ligne. Maintenez depth à une valeur faible lors des appels de liste afin de réduire la taille de la charge utile, et demandez une ressource spécifique par identifiant lorsque vous avez besoin de détails complets.

1.2 Remarque sur les hôtes API distincts

Tous les services IONOS CLOUD ne sont pas hébergés 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 l'adresse finale depuis la documentation de ce service plutôt que de supposer l'adresse de base du CloudAPI principal. L'en-tête d'authentification, en revanche, reste le même jeton bearer sur ces hôtes.

2. Authentification

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

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

2.1 Jetons porteurs via le Token Manager

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

# 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 d'accès de génération de jetons, puis réutiliser la valeur de ce jeton pour les appels ultérieurs à l'API et au SDK :

# 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 des jetons est auth/v1, et non cloudapi/v6. Le jeton que vous recevez est ensuite utilisé avec CloudAPI.

2.2 Cycle de vie des jetons : création, périmètre et rotation

Le Token Manager impose des limites concrètes auxquelles vous devez prendre garde lors de la conception. Vous pouvez générer jusqu'à 100 jetons d'authentification par utilisateur, et la durée de vie (TTL) de chaque jeton est choisie à 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 plus récupérable par la suite ; vous pouvez également la télécharger au format fichier à ce moment-là. Capturez-la immédiatement dans votre magasin de secrets, car il n'y a pas d'option « afficher à nouveau » ultérieurement.

Ces limites favorisent un modèle à privilèges minimaux et adapté à la rotation. Émettez un jeton distinct à TTL courte pour chaque service et pour chaque environnement (un pour le pipeline CI de TaskBoard, un pour le service API en cours d'exécution, et ainsi de suite) plutôt que de partager un seul jeton à longue durée de vie partout. Comme les jetons expirent selon un TTL fixe, la rotation est une routine que vous automatisez plutôt qu'une urgence à gérer.

# 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.

La limite de 100 jetons signifie qu'un script incontrôlé qui génère un nouveau jeton à chaque exécution épuisera votre quota. Générez-le une seule fois, stockez-le, réutilisez-le jusqu'à son expiration, puis effectuez une rotation.

3. Le modèle d'approvisionnement asynchrone

C'est la règle qui provoque plus de pannes dans l'automatisation IONOS CLOUD que toute autre : les opérations d'approvisionnement sont asynchrones. Un POST ou un PUT ne renvoie pas une ressource terminée. Il renvoie 202 Accepted, la nouvelle ressource entre dans un état BUSY, et un en-tête Location pointe vers une URL d'état que vous interrogez jusqu'à la fin de l'approvisionnement.

Vous devez attendre la complétion 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 datacenter partiellement approvisionné, échoue. Le modèle asynchrone n'est pas optionnel, et ce 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 le id de la nouvelle ressource, et l'en-tête de la réponse inclut 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:'

L'en-tête Location contient l'URL de l'état de la requête. Le schéma est identique pour tous les types de ressources : la documentation des points d'accès de l'API Cloud principale indique que la réponse inclut un en-tête Location avec une URL permettant d'interroger l'état de la requête, et que la ressource conserve un statut BUSY jusqu'à la fin de la mise en service.

3.2 Interrogation jusqu'à DONE

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

La structure exacte de la charge utile de l'état de la requête et la cadence d'interrogation recommandée ci-dessous reflètent les pratiques courantes d'automatisation IONOS CLOUD, plutôt qu'un extrait de documentation verbatim. Les valeurs d'état BUSY, DONE et FAILED sont fondées sur la documentation ; la structure de la boucle est une implémentation 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 du SDK qui attend l'achèvement, et le client effectue le sondage en interne, de sorte que le code de votre application semble comme si l'appel était synchrone, tout en respectant le modèle asynchrone sous-jacent.

4. SDK et CLI ionosctl

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

4.1 Le SDK Python

Le SDK Python utilise un objet Configuration (contenant votre jeton) encapsulé dans un ApiClient, que vous transmettez ensuite aux classes API spécifiques à chaque service.

Les noms de classes et de méthodes du SDK ci-dessous (Configuration, ApiClient, DataCentersApi, ServersApi, et la méthode datacenters_servers_post) reflètent l'interface publiée du SDK Python ionoscloud selon les connaissances générales ; vérifiez les signatures exactes par rapport à la version du SDK que vous avez fixé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. Maintenez la durée de vie de cet objet liée à la durée de vie (TTL) du jeton et mettez-le à jour lors de sa rotation.

4.2 L'interface en ligne de commande ionosctl

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

La syntaxe de la commande ionosctl ci-dessous reflète la structure de commandes publiée de l'outil selon les connaissances générales ; vérifiez les options par rapport à la version de l'interface en ligne de commande installée à l'aide de 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 Choisir une interface

Le tableau suivant compare les quatre façons d'interagir avec l'API IONOS CLOUD afin que vous puissiez choisir de manière délibérée plutôt que par habitude.

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

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

L'automatisation en production rencontre trois réalités que les exemples du cas nominal omettent : l'API limite votre débit, les collections sont paginées, et certains codes d'erreur ont une signification différente de celle que vous attendez.

5.1 Limitation de débit avec un retour exponentiel

Lorsque vous dépassez le taux de requêtes, l'API répond avec 429. La bonne réponse est d'appliquer un retour exponentiel et de réessayer, plutôt que de bombarder le point d'accès.

L'implémentation du retour exponentiel ci-dessous est un modèle standard de nouvelle tentative côté client ; la sémantique du statut 429 est fondée sur la documentation, tandis que les délais spécifiques et l'ajout d'aléa relèvent d'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 offset et limit

Les points d'accès 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 au sein de la collection. Sur les points d'accès de collection, la valeur par défaut de limit est 1000 et la valeur par défaut de 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 renvoyé l'intégralité des données. Si vous avez reçu exactement limit éléments, il y a presque certainement une autre page.

5.3 Gestion des erreurs et le piège du 404

L'erreur que vous allez d'abord mal interpréter est 404 lors de la provision. 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 est manquante. C'est le modèle asynchrone qui vous joue des tours : vous avez omis la sonde et vous avez interrogé une ressource enfant avant que sa ressource parente n'atteigne l'état 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 d'IONOS CLOUD incluent une charge utile structurée avec le code HTTP et un message lisible par un humain ; journalisez-le plutôt que d'avaler l'exception, afin qu'un 429, un corps mal formé (422) et un échec d'authentification (401) soient immédiatement distinguables dans la sortie de votre pipeline.

Fiche de référence rapide de l'API

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

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

Atelier de code

Objectif : Provisionner un serveur de trois manières (curl, SDK Python, 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 SDK Python ionoscloud : 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 datacenter et capturer l'URL d'état de la requête

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 datacenter 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 SDK Python

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 : Lister 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 contrôle de validation :

• [ ] Jeton généré et exporté, jamais codé en dur
• [ ] Centre de données atteint DONE avant la création de tout serveur
• [ ] 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. Considérer le provisionnement comme synchrone

   • Problème : Votre script crée un serveur et attache immédiatement un volume, ce qui provoque une erreur intermittente 404 ou une erreur de conflit.
   • Cause : La POST renvoie 202 Accepted avec la ressource dans l'état BUSY ; la ressource n'est pas encore prête.
   • Solution : Interrogez l'URL d'état de l'en-tête Location jusqu'à ce que DONE soit atteint, ou utilisez l'option d'attente de l'achèvement du SDK, avant tout appel dépendant.

2. Générer un nouveau jeton à chaque exécution

   • Problème : Un planifié cesse de fonctionner après un certain temps en raison d'erreurs d'authentification, et vous trouvez des dizaines de jetons dans le Token Manager.
   • Cause : Chaque utilisateur est limité à 100 jetons ; un script qui en génère un par exécution épuise le quota et perd la trace du jeton actif.
   • Solution : Générez un jeton avec portée par service/environnement, stockez-le dans un coffre de secrets, réutilisez-le jusqu'à l'expiration de sa durée de vie, puis effectuez une rotation. La valeur du jeton n'est affichée qu'une seule fois, donc capturez-la lors de la création.

3. Lire uniquement 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.
   • Cause : Les points d'entrée de collection utilisent la pagination avec une limit par défaut de 1000 ; le code qui ignore offset/limit ne voit qu'une seule page.
   • Solution : Bouclez avec une offset croissante jusqu'à ce qu'une page renvoie moins de limit éléments (voir la section 5.2).

Résumé

Vous disposez désormais du contrat sur lequel chaque unité ultérieure repose. Vous pouvez vous authentifier à l'aide d'un jeton bearer issu du Token Manager, respecter le modèle de provisionnement asynchrone en interrogeant requests/{id}/status jusqu'à ce que DONE soit atteint, et provisionner la même ressource via curl, le SDK Python et ionosctl. Vous pouvez également maintenir l'automatisation opérationnelle sous charge en appliquant un recul sur 429 et en parcourant les grandes collections par pages. Grâce à cette base, les travaux d'infrastructure de TaskBoard dans l'unité 1.2 consistent à exprimer ces mêmes opérations de manière déclarative dans 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 renvoie 202 Accepted, la ressource passe à l'état BUSY, et vous interrogez l'URL d'état Location jusqu'à DONE avant les opérations dépendantes.
• Utilisez des jetons bearer (l'authentification Basic est en cours de suppression et les comptes 2FA doivent utiliser le bearer) ; 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 n'est affichée qu'une seule fois et n'est pas récupérable, il faut donc la capturer à la création ; vous pouvez la télécharger au format fichier à ce moment-là.
• Un 404 juste après la création signifie généralement « pas encore prêt », et non « introuvable » ; gérez 429 avec un recul exponentiel et parcourez les collections avec offset/limit (limite par défaut 1000).

Terminologie importante :

• Jeton bearer : une chaîne d'identifiants émise par le Token Manager, envoyée dans l'en-tête Authorization: Bearer, et la méthode d'authentification principale pour l'API IONOS CLOUD.
• Modèle de provisionnement asynchrone : le comportement de la plateforme selon lequel les appels de création/mise à jour renvoient 202 et une URL d'état Location ; la ressource est BUSY jusqu'à ce que le provisionnement atteigne DONE.
• Point d'accès d'état de la requête : /cloudapi/v6/requests/{id}/status, interrogé pour savoir si une opération asynchrone est BUSY, DONE ou FAILED.
• Durée de vie d'un jeton (TTL) : la durée de vie fixe choisie à la création du jeton (de 1 heure à 365 jours) qui détermine votre calendrier de rotation.
• Pagination (offset/limit) : paramètres des points d'accès de collection où limit limite le nombre d'éléments par page (valeur par défaut 1000) et offset définit l'index de départ.

Prochaines étapes

Continuer l'apprentissage : Unité 1.2 : Terraform Provider and Core Patterns

Sujets connexes :

• Unité 1.2 : Terraform Provider and Core Patterns
• Unité 1.3 : Knowledge Check - Programmatic Foundations