Unidad 1.1: IONOS CLOUD API, autenticación y modelo asíncrono

Introducción

Está a punto de construir TaskBoard, una API de gestión de tareas con un frontend web, y desplegar cada componente a través de código en IONOS CLOUD. Sin necesidad de hacer clic por el Data Center Designer. Antes de poder aprovisionar un solo servidor, necesita tres elementos configurados correctamente: cómo se autentica, cómo la API le indica que un recurso está realmente listo y qué cliente (HTTP sin procesar, SDK o CLI) utiliza en cada situación.

Esta unidad es el contrato que firma con la API de IONOS CLOUD. El hecho más importante que debe interiorizar es que el aprovisionamiento es asíncrono: una POST devuelve de inmediato un ID de solicitud, no un recurso finalizado. Considere la respuesta como "aceptado, en proceso" en lugar de "completado", y evitará la clase más común de error de automatización en esta plataforma. Configuará la autenticación, aprenderá el bucle de sondeo que controla cada operación dependiente y aprovisionará un servidor a través de las tres interfaces para que pueda compararlas directamente.

1. La API REST de IONOS CLOUD

Cada recurso de TaskBoard que cree, desde el centro de datos hasta el servidor y el equilibrador de carga, se gestiona a través de la API REST de IONOS CLOUD. La API de Cloud está versionada y se encuentra bajo una única URL base. Todas las llamadas principales de CloudAPI apuntan a https://api.ionos.com/cloudapi/v6, y las solicitudes y respuestas están en formato JSON (Content-Type: application/json).

Los recursos se dirigen de forma jerárquica. Un servidor, por ejemplo, se encuentra bajo su centro de datos: /datacenters/{datacenterId}/servers/{serverId}. Esta estructura anidada es importante porque casi siempre se crea un recurso padre antes que un recurso hijo, y el recurso padre debe estar completamente aprovisionado primero (consulte la sección 3).

1.1 URL base, versionado y tipos de contenido

La superficie de CloudAPI está fijada a v6 en la ruta. Fije esta versión de forma explícita en su código, en lugar de confiar en un alias sin versión, para que un cambio de versión aguas arriba no modifique el comportamiento de su automatización de forma silenciosa.

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

El parámetro de consulta depth controla la cantidad del árbol de recursos anidados que se devuelve. depth=1 devuelve la colección con las propiedades de nivel superior; las profundidades superiores incluyen los elementos hijos de forma integrada. Mantenga depth bajo en las llamadas de lista para reducir el tamaño de la carga, y solicite un recurso específico por ID cuando necesite el detalle completo.

1.2 Nota sobre hosts de API separados

No todos los servicios de IONOS CLOUD se encuentran bajo cloudapi/v6. Algunos servicios exponen sus propios hosts (por ejemplo, IAM Federation utiliza https://iam.ionos.com, y el CDN utiliza un host regional). Cuando integre esos servicios en módulos posteriores, lea el punto de final desde la documentación de ese servicio en lugar de suponer la base de CloudAPI principal. Sin embargo, la cabecera de autenticación permanece como el mismo token bearer en estos hosts.

2. Autenticación

La API de IONOS CLOUD acepta dos métodos de autenticación: un token de portador (el método principal y recomendado) y la autenticación básica utilizando el nombre de usuario y la contraseña de su cuenta.

Dos hechos operativos determinan la elección. En primer lugar, las cuentas con 2FA habilitado o impuesto deben utilizar la autenticación con token de portador. En segundo lugar, la autenticación básica está documentada como descontinuada en un futuro próximo y solo debe utilizarse en combinación con 2FA. La conclusión práctica para cualquier automatización nueva: utilice tokens de portador.

2.1 Tokens de portador mediante el Token Manager

Genera tokens a través del Token Manager de autenticación de API/SDK (en el DCD, bajo Menú > Gestión > Token Manager, mediante la API o mediante la CLI). Un token es una cadena de caracteres que coloca en la cabecera Authorization en cada solicitud.

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

Puede solicitar un token de forma programática desde el punto de finalización de generación de tokens y, a continuación, reutilizar el valor de ese token para las llamadas posteriores a la API y al 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"

Observe que el host de generación de tokens es auth/v1, no cloudapi/v6. El token que se devuelve se utiliza luego contra CloudAPI.

2.2 Ciclo de vida del token: creación, alcance y rotación

Token Manager impone límites concretos en los que debe basar su diseño. Puede generar hasta 100 tokens de autenticación por usuario, y el TTL de cada token se elige en el momento de la creación a partir de un conjunto fijo de opciones: 1 hora, 4 horas, 1 día, 7 días, 30 días, 60 días, 90 días, 180 días y 365 días.

El valor del token se muestra exactamente una vez en la generación y no es recuperable después; también puede descargarlo como archivo en ese momento. Captúrelo inmediatamente en su almacén de secretos, porque no existe una opción de "mostrar de nuevo" más tarde.

Estos límites dan forma a un patrón de privilegios mínimos y apto para la rotación. Emita un token separado con TTL corto por servicio y por entorno (uno para la pipeline de CI de TaskBoard, uno para el servicio API en ejecución, y así sucesivamente) en lugar de compartir un token de larga vida en todas partes. Dado que los tokens caducan según un TTL fijo, la rotación es una rutina que automatiza en lugar de una emergencia.

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

El límite de 100 tokens significa que un script descontrolado que emita un token nuevo en cada ejecución agotará su cuota. Emita el token una sola vez, almacénelo, reutilícelo hasta su vencimiento y luego realice una rotación.

3. El modelo de aprovisionamiento asíncrono

Esta es la regla que rompe más automatizaciones en IONOS CLOUD que cualquier otra: las operaciones de aprovisionamiento son asíncronas. Una operación de POST o PUT no devuelve un recurso terminado. Devuelve 202 Accepted, el nuevo recurso entra en un estado de BUSY, y una cabecera de Location apunta a una URL de estado que debe consultar repetidamente hasta que el aprovisionamiento se complete.

Debe esperar la finalización antes de cualquier operación que dependa del nuevo recurso. Adjuntar un volumen a un servidor que aún está en estado BUSY, o crear una NIC en un centro de datos parcialmente aprovisionado, resultará en un error. El modelo asíncrono no es opcional, y no es algo que pueda eludir simplemente reintentando la llamada dependiente.

3.1 La respuesta 202 y la cabecera Location

Cuando crea un recurso, el código de estado de la respuesta es 202 Accepted, el cuerpo contiene el id del nuevo recurso, y la cabecera de la respuesta incluye una URL de estado para consultar.

# 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:'

La cabecera Location transporta la URL del estado de la solicitud. El patrón es idéntico en todos los tipos de recursos: la documentación de los puntos de acceso principales de la API de Cloud indica que la respuesta incluye una cabecera Location con una URL para consultar el estado de la solicitud, y el recurso mantiene un estado BUSY hasta que la aprovisionamiento se completa.

3.2 Consulta periódica hasta DONE

El punto de acceso de estado informa sobre el estado de la solicitud. Se consulta de forma periódica hasta que el estado sea DONE (un aprovisionamiento fallido se manifiesta como FAILED). Solo entonces se procede a las operaciones dependientes.

La forma exacta de la carga útil del estado de la solicitud y la cadencia de consulta recomendada a continuación reflejan la práctica común de automatización de IONOS CLOUD, en lugar de ser un extracto literal de la documentación. Los valores de estado BUSY, DONE y FAILED están fundamentados en la documentación; la estructura del bucle es una implementación estándar.

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

Los SDK encapsulan este ciclo por usted. Si pasa la opción del SDK que espera la finalización, el cliente realiza sondeos de forma interna, de modo que el código de su aplicación se lee como si la llamada fuera síncrona, aunque sigue respetando el modelo asíncrono subyacente.

4. SDKs y la CLI ionosctl

No escribirá curl sin procesar para la lógica de la aplicación. IONOS CLOUD publica SDKs para Python (ionoscloud), Go (sdk-go), Java y JavaScript, además de la herramienta de línea de comandos ionosctl. Todos ellos se autentican con el mismo token de portador y todos ellos deben respetar el modelo asíncrono.

4.1 El SDK de Python

El SDK de Python utiliza un objeto Configuration (que contiene su token) envuelto en un ApiClient, que luego se pasa a las clases de API específicas del servicio.

Los nombres de clases y métodos del SDK a continuación (Configuration, ApiClient, DataCentersApi, ServersApi y el método datacenters_servers_post) reflejan la interfaz publicada del SDK de Python ionoscloud según el conocimiento general; verifique las firmas exactas contra la versión del SDK que utilice.

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)

El SDK lee su token del objeto Configuration. Mantenga el tiempo de vida de ese objeto vinculado al TTL del token y actualícelo cuando lo rote.

4.2 La CLI ionosctl

ionosctl es la interfaz más rápida para tareas puntuales, scripting e inspección. Autentíquese una vez y luego ejecute comandos.

La sintaxis del comando ionosctl a continuación refleja la estructura de comandos publicada de la herramienta según el conocimiento general; confirme las banderas con su versión instalada de la CLI mediante 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 Elección de una interfaz

La siguiente tabla compara las cuatro formas en que interactúa con la API de IONOS CLOUD, para que pueda elegir de manera deliberada y no por costumbre.

Como se muestra arriba, utilice el SDK para la lógica de la aplicación, ionosctl para tareas rápidas y pegamento de CI, HTTP crudo cuando esté depurando el propio protocolo, y Terraform (próxima unidad) para todo lo que debería existir como estado declarativo.

5. Limitación de velocidad, paginación y manejo de errores

La automatización en producción se enfrenta a tres realidades que los ejemplos de casos exitosos omiten: la API limita su velocidad de solicitud, las colecciones están paginadas y algunos códigos de error significan algo diferente a lo que se espera.

5.1 Limitación de velocidad con reintentos con retroceso exponencial

Cuando se supera la velocidad de solicitud, la API responde con 429. La respuesta correcta es aplicar un retroceso exponencial y reintentar, no enviar solicitudes de forma continua al punto de acceso.

La implementación de retroceso exponencial a continuación es un patrón estándar de reintento en el lado del cliente; la semántica del estado 429 está fundamentada en la documentación, mientras que los retrasos y la variación específicos son una decisión de implementación.

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 Paginación con desplazamiento y límite

Los puntos finales de lista devuelven colecciones paginadas controladas por offset y limit. El parámetro limit limita el número de elementos por página, y offset establece el punto de inicio dentro de la colección. En los puntos finales de colección, el valor predeterminado de limit es 1000 y el valor predeterminado de offset es 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

Nunca asuma que una sola llamada devolvió todo. Si recibió exactamente limit elementos, casi con seguridad existe otra página.

5.3 Manejo de errores y la trampa del 404

El error que leerá incorrectamente primero es 404 durante la aprovisionamiento. Un 404 inmediatamente después de crear un recurso generalmente significa que el recurso aún no está listo, no que falta. Este es el modelo asíncrono que le está afectando: omitió la consulta por sondeo y consultó un recurso hijo antes de que su padre alcanzara 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)

Ler los cuerpos de respuesta en caso de fallo. Las respuestas de error de IONOS CLOUD incluyen una carga estructurada con el código HTTP y un mensaje legible por humanos; regístrela en lugar de suprimir la excepción, de modo que un 429, un cuerpo malformado (422) y un fallo de autenticación (401) sean distinguibles de inmediato en la salida de su pipeline.

Tarjeta rápida de referencia de la API

Puntos finales de la API clave para la autenticación y el modelo asíncrono:

URL base: https://api.ionos.com/cloudapi/v6 Host del token: https://api.ionos.com/auth/v1 Autenticación: Authorization: Bearer <token>

Laboratorio de código

Objetivo: Aprovisionar un servidor de tres maneras (curl, SDK de Python, ionosctl) y verificar la finalización asíncrona en cada caso.

Requisitos previos:

• Cuenta de IONOS CLOUD con acceso a la API
• curl, python3 y ionosctl instalados localmente
• El SDK de Python ionoscloud: pip install ionoscloud

Paso 1: Generar y exportar un token

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"])')

Salida esperada:

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

Paso 2: Crear un centro de datos y capturar la URL de estado de la solicitud

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"])')

Salida esperada:

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

Paso 3: Realizar consultas periódicas hasta que el centro de datos esté COMPLETADO

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

Salida esperada:

done

Paso 4: Crear un servidor mediante 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"}}'

Salida esperada:

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

Paso 5: Crear un servidor mediante el SDK de 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)

Salida esperada:

sdk server: <server-id>

Paso 6: Crear un servidor con ionosctl

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

Salida esperada:

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

Paso 7: Listar todos los servidores y confirmar que existen tres

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

Salida esperada:

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

Lista de verificación de validación:

• [ ] Token generado y exportado, nunca codificado de forma estática
• [ ] El centro de datos alcanzó DONE antes de que se creara cualquier servidor
• [ ] Tres servidores creados a través de tres interfaces diferentes
• [ ] Los tres servidores alcanzan el estado AVAILABLE

Limpieza:

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

Errores comunes

1. Tratar la aprovisionamiento como síncrono

   • Problema: Su script crea un servidor y adjunta un volumen de inmediato, lo que produce un error intermitente 404 o un error de conflicto.
   • Por qué ocurre: La POST devolvió 202 Accepted con el recurso en estado BUSY; el recurso aún no está listo.
   • Solución: Realice consultas periódicas a la URL de estado desde la cabecera Location hasta que se alcance DONE, o utilice la opción de espera de finalización del SDK, antes de cualquier llamada dependiente.

2. Generar un token nuevo en cada ejecución

   • Problema: Un trabajo programado deja de funcionar después de un tiempo con errores de autenticación, y usted encuentra decenas de tokens en el Token Manager.
   • Por qué ocurre: Cada usuario tiene un límite de 100 tokens; un script que genera uno por ejecución agota la cuota y pierde el rastro de qué token está activo.
   • Solución: Genere un token con ámbito específico por servicio/entorno, almacénelo en un almacén de secretos, reutilícelo hasta que su TTL expire y luego realice la rotación. El valor del token solo se muestra una vez, por lo que debe capturarlo en el momento de la creación.

3. Leer solo la primera página de una colección

   • Problema: Una operación de lista omite silenciosamente los recursos que superan los primeros 1000 elementos.
   • Por qué ocurre: Los puntos de acceso de colección usan paginación con un limit predeterminado de 1000; el código que ignora offset/limit solo ve una página.
   • Solución: Itere con un offset creciente hasta que una página devuelva menos de limit elementos (véase la sección 5.2).

Resumen

Ahora posee el contrato sobre el que dependen todas las unidades posteriores. Puede autenticarse con un token de portador del Token Manager, respetar el modelo de aprovisionamiento asíncrono consultando requests/{id}/status hasta que se alcance DONE, y aprovisionar el mismo recurso mediante curl, el SDK de Python y ionosctl. También puede mantener la automatización activa bajo carga aplicando un retroceso ante 429 y paginando colecciones grandes. Con esta base, el trabajo de infraestructura de TaskBoard en la Unidad 1.2 se convierte en una cuestión de expresar estas mismas operaciones de forma declarativa en Terraform.

Puntos clave:

• La URL base de CloudAPI es https://api.ionos.com/cloudapi/v6; los tokens se generan en https://api.ionos.com/auth/v1/tokens/generate.
• El aprovisionamiento es asíncrono: POST devuelve 202 Accepted, el recurso pasa a BUSY, y usted consulta la URL de estado Location hasta DONE antes de las operaciones dependientes.
• Utilice tokens de portador (la autenticación básica está en proceso de descontinuación y las cuentas con 2FA deben usar tokens de portador); un usuario puede tener hasta 100 tokens, cada uno con una TTL fija de 1 Hora a 365 Días.
• El valor de un token se muestra exactamente una vez y no es recuperable, por lo que debe capturarlo en el momento de la creación; en ese instante puede descargarlo como archivo.
• Un 404 inmediatamente después de la creación suele significar "aún no está listo", no "no existe"; maneje 429 con retroceso exponencial y pague las colecciones con offset/limit (límite predeterminado 1000).

Terminología importante:

• Token de portador: Una credencial en forma de cadena emitida por el Token Manager, enviada en la cabecera Authorization: Bearer, y el método de autenticación principal para la API de IONOS CLOUD.
• Modelo de aprovisionamiento asíncrono: El comportamiento de la plataforma en el que las llamadas de creación/actualización devuelven 202 y una URL de estado Location; el recurso permanece en BUSY hasta que el aprovisionamiento alcanza DONE.
• Punto de acceso de estado de solicitud: /cloudapi/v6/requests/{id}/status, consultado para saber si una operación asíncrona está en BUSY, DONE, o FAILED.
• TTL del token: La vida útil fija elegida en la creación del token (de 1 Hora a 365 Días) que determina su calendario de rotación.
• Paginación (offset/limit): Parámetros del punto de acceso de colecciones donde limit limita los elementos por página (predeterminado 1000) y offset establece el índice de inicio.

Próximos pasos

Siga aprendiendo: Unidad 1.2: Terraform Provider and Core Patterns

Temas relacionados:

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