Unidad 1.1: IONOS CLOUD API, autenticación y modelo asíncrono
Introducción
A lo largo de este curso, usted construirá TaskBoard, una API de gestión de tareas con un frontend web, aprovisionada y desplegada completamente mediante código desde un repositorio Git.
Antes de escribir cualquier código de Terraform, necesita comprender la capa con la que interactúa cada herramienta: la API de IONOS CLOUD. Terraform, ionosctl y los SDK envían las mismas solicitudes HTTP que usted puede enviar con curl. Cuando un pipeline falla, la causa suele ser un problema de autenticación, una solicitud que se ejecutó antes de que su predecesora terminara, o un cliente que ignoró un límite de tasa.
En esta unidad, usted generará tokens de acceso, llamará directamente a la API v6, manejará su modelo de solicitud asíncrono y añadirá reintentos con retroceso y paginación a un pequeño cliente en Python. En el laboratorio de código, aprovisionará el primer centro de datos y los servidores de TaskBoard de tres maneras.
1. La IONOS CLOUD API v6
La IONOS CLOUD API v6 es la API REST de infraestructura principal. Cubre recursos de cómputo, contenedores, redes y copias de seguridad en una única especificación OpenAPI, versión 6.0.
curl --request GET 'https://api.ionos.com/cloudapi/v6/datacenters' \
--header 'Authorization: Bearer <access_token>'
1.1 URL base y versionado
La URL base para la API v6 es https://api.ionos.com/cloudapi/v6. Productos como Managed Kubernetes, Cross Connect, Flow Logs y Backup Service se administran a través de endpoints bajo /cloudapi/v6. Los servicios más recientes, como CDN, VPN Gateway y los servicios de base de datos, se publican como especificaciones de API independientes con sus propias URLs base y versionado.
Para DBaaS for PostgreSQL, DBaaS for MariaDB y DBaaS for In-Memory DB, utilice las API v2. Estas se ejecutan en hosts regionales con una ruta /v2:
export PG_API="https://postgresql.de-txl.ionos.com/v2"
export MARIADB_API="https://mariadb.de-txl.ionos.com/v2"
Usted utiliza estas API en el Módulo 2. La regla por ahora: verifique la URL base de cada API antes de llamarla.
1.2 Estructura de la solicitud y parámetros de consulta
Envíe JSON con Content-Type: application/json. En las solicitudes GET, depth (de 0 a 10, valor predeterminado 0) controla cuántos niveles de objetos hijos expande la respuesta, y pretty (valor predeterminado true) lo imprime con formato legible.
curl --silent 'https://api.ionos.com/cloudapi/v6/datacenters?depth=1' \
--header "Authorization: Bearer ${IONOS_TOKEN}" | jq '.items[].properties.name'
2. Autenticación
La API v6 acepta dos métodos: un token de portador (Authorization: Bearer <access_token>) y Basic Auth (Authorization: Basic <base64(username:password)>). Utilice tokens de portador para cada carga de trabajo automatizada.
2.1 Emisión de un token de acceso
Ambos métodos llaman al mismo endpoint de la API de autenticación, GET https://api.ionos.com/auth/v1/tokens/generate. La respuesta contiene un JSON Web Token (JWT) en el campo token.
# Option A: bootstrap with your credentials (Basic Auth)
BASIC=$(printf '%s' 'username:password' | base64)
curl --silent --request GET 'https://api.ionos.com/auth/v1/tokens/generate?ttl=86400' \
--header "Authorization: Basic ${BASIC}" | jq -r '.token'
# Option B: mint a new access token with an existing secure token
curl --silent --request GET 'https://api.ionos.com/auth/v1/tokens/generate?ttl=86400' \
--header "Authorization: Bearer ${SECURE_TOKEN}" | jq -r '.token'
El parámetro de consulta ttl establece la vida útil del token en segundos: mínimo 60, máximo 31536000, y por defecto un token generado expira después de un año. Las vidas útiles cortas limitan el daño causado por una fuga.
Dos reglas limitan la autenticación básica. Las cuentas con autenticación de dos factores habilitada o forzada deben utilizar la autenticación con token de portador. El método de autenticación básica también se discontinuará en un futuro próximo, por lo que no debe construir nuevas automatizaciones sobre él.
2.2 Token Manager y ciclo de vida del token
En Data Center Designer (DCD), Token Manager se encuentra bajo Menú > Gestión > Token Manager. Genera tokens con uno de estos valores de tiempo de vida (TTL): 1 hora, 4 horas, 1 día, 7 días, 30 días, 60 días, 90 días, 180 días o 365 días.
Tres hechos determinan el manejo de los tokens:
- El valor del token se muestra solo una vez, en el momento de la generación. En ese momento, puede descargarlo como un archivo de texto.
- Puede tener hasta 100 tokens activos por usuario. Al alcanzar este límite, la API devuelve un error para los nuevos tokens.
- Eliminar un token en Token Manager lo desactiva de inmediato, incluso si no ha expirado.
Mantenga el valor en un almacén de secretos e inyéctelo como variable de entorno:
export IONOS_TOKEN="$(vault kv get -field=token secret/taskboard/ionos)"
2.3 Alcance con privilegios mínimos
Para limitar las acciones que puede realizar un token, genérelo bajo un subusuario dedicado cuyos grupos otorguen únicamente los privilegios que el servicio necesita. Los privilegios son concesiones para acciones específicas, como createDatacenter, createSnapshot o reserveIp. Las autorizaciones de recursos son Read, Edit y Sharing.
Para TaskBoard, cree taskboard-ci para cambios de infraestructura y un usuario de solo lectura para los scripts de monitorización. De este modo, un token de monitorización que se filtre no podrá crear recursos.
3. El modelo aprovisionamiento asíncrono
Para la API v6, los recursos se crean de forma asíncrona. Una POST que crea un recurso devuelve 202 Accepted mientras el aprovisionamiento sigue en ejecución, y la cabecera de respuesta Location contiene una URL de callback para consultar el estado de la operación.
curl --include --request POST 'https://api.ionos.com/cloudapi/v6/datacenters' \
--header "Authorization: Bearer ${IONOS_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{"properties": {"name": "taskboard-dev", "location": "de/txl"}}'
HTTP/1.1 202 Accepted
Location: https://api.ionos.com/cloudapi/v6/requests/<requestId>/status
...
"metadata": { "state": "BUSY" }
3.1 Consulta del estado de la solicitud
GET /requests/{requestId}/status devuelve metadata.status, que es uno de QUEUED, RUNNING, DONE o FAILED. La consulta no es opcional: un recurso BUSY tiene al menos una solicitud de modificación pendiente, y todas las solicitudes siguientes se encolan detrás de ella.
import time
import requests
def wait_for_request(session, status_url, timeout=600):
"""Poll a request status URL until DONE; raise on FAILED or timeout."""
deadline = time.monotonic() + timeout
delay = 2
while time.monotonic() < deadline:
resp = session.get(status_url)
resp.raise_for_status()
meta = resp.json()["metadata"]
if meta["status"] == "DONE":
return
if meta["status"] == "FAILED":
raise RuntimeError(f"Request failed: {meta.get('message')}")
time.sleep(delay)
delay = min(delay * 2, 30)
raise TimeoutError(f"Request not DONE after {timeout}s: {status_url}")
3.2 Dos tipos de errores
La validación de fallo rápido se ejecuta primero: autorización, recursos del contrato y si la configuración es compatible con el producto y la ubicación. Estos errores se devuelven de forma síncrona, y la API solo devuelve el primer error de validación que encuentra, por lo que una nueva solicitud puede revelar el siguiente.
Los errores de aprovisionamiento ocurren más tarde y aparecen en el estado de la solicitud, con un código de error en el formato VDC-x-xxx. Revise tanto la respuesta de POST como el estado final de la solicitud.
4. Construcción de un cliente resiliente
4.1 Limitación de velocidad y retroceso
Cuando se supera el límite de velocidad de solicitudes, la API devuelve 429. Tres cabeceras de respuesta le permiten regular el tráfico antes de que eso ocurra:
| Cabecera | Significado |
|---|---|
X-RateLimit-Remaining |
Solicitudes que aún pueden realizarse sin provocar una respuesta de error |
X-RateLimit-Limit |
Número medio de solicitudes por minuto permitido |
X-RateLimit-Burst |
Número máximo de solicitudes de API simultáneas permitidas |
Envuelva cada llamada en un reintento con retroceso exponencial y aleatorización:
import random
RETRYABLE = {429, 500, 503}
def call(session, method, url, max_attempts=6, **kwargs):
for attempt in range(max_attempts):
resp = session.request(method, url, **kwargs)
if resp.status_code not in RETRYABLE:
return resp
retry_after = resp.headers.get("Retry-After")
delay = float(retry_after) if retry_after else min(2 ** attempt, 60)
time.sleep(delay + random.uniform(0, 1))
resp.raise_for_status()
return resp
4.2 Paginación
Las colecciones aceptan offset (predeterminado 0) y limit (mínimo 1, máximo 10000). La respuesta contiene _links.next solo cuando offset + limit es menor que el número total de elementos.
def list_all(session, url, page_size=100):
params = {"offset": 0, "limit": page_size}
while url:
page = call(session, "GET", url, params=params).json()
yield from page.get("items", [])
url = page.get("_links", {}).get("next")
params = None # the next URL already carries offset and limit
4.3 Códigos de estado y cuerpos de error
Las respuestas de error incluyen httpStatus y un arreglo messages de errorCode y message:
{ "httpStatus": 422, "messages": [ { "errorCode": "200", "message": "[VDC-yy-xxxx] ..." } ] }
| Código | Acción del cliente |
|---|---|
401 |
Emitir un nuevo token; verificar su caducidad |
403 |
Verificar los privilegios de grupo del usuario |
404 |
Verificar el UUID y que la solicitud de creación sea DONE |
409 |
Esperar a que el recurso salga de BUSY y, a continuación, reintentar |
422 |
Corregir el cuerpo de la solicitud |
429, 500, 503 |
Reintentar con backoff; contactar al soporte si un 500 persiste |
5. SDKs e ionosctl
5.1 Los SDKs
Los SDKs que encapsulan la API v6 están disponibles para Go, Java, Ruby, Python y NodeJS, publicados en github.com/ionos-cloud/sdk-go, sdk-java, sdk-ruby, sdk-python y sdk-nodejs. Su documentación se encuentra en https://docs.ionos.com/cloud/sdk-tools-home. Los SDKs encapsulan la misma API, por lo que la regla asíncrona de la Sección 3 se aplica sin cambios. Esta unidad utiliza HTTP plano en Python para que cada encabezado quede visible.
5.2 ionosctl
Instale ionosctl con un gestor de paquetes:
brew tap ionos-cloud/homebrew-ionos-cloud && brew install ionosctl # Homebrew
snap install ionosctl # snap
scoop install ionos-cloud/ionosctl # Scoop
ionosctl verifica primero las variables de entorno (IONOS_TOKEN, o IONOS_USERNAME y IONOS_PASSWORD), y luego su archivo de configuración. Para escribir un archivo de configuración, ejecute ionosctl config login --token "$IONOS_TOKEN".
ionosctl compute datacenter list
ionosctl compute server list --all
ionosctl compute request list --cols RequestId,Method,Status,Message,Targets
ionosctl compute request wait --request-id REQUEST_ID --timeout 120
Los comandos de creación aceptan --wait (-w) para bloquear la ejecución hasta que el recurso esté AVAILABLE. --timeout limita la espera, con un valor predeterminado de 600 segundos.
Tarjeta rápida de referencia de la API
Endpoints principales de la API para el tema de esta unidad:
| Método | Endpoint | Descripción |
|---|---|---|
GET |
https://api.ionos.com/auth/v1/tokens/generate |
Emitir un nuevo token de acceso (ttl en segundos) |
GET |
/datacenters |
Listar centros de datos (offset, limit, depth) |
POST |
/datacenters |
Crear un centro de datos (devuelve 202 y Location) |
POST |
/datacenters/{datacenterId}/servers |
Crear un servidor |
GET |
/requests/{requestId}/status |
Consultar una solicitud asíncrona: QUEUED, RUNNING, DONE, FAILED |
URL base: https://api.ionos.com/cloudapi/v6
Autenticación: Authorization: Bearer <token>
Laboratorio de código
Objetivo: Aprovisionar el centro de datos de desarrollo de TaskBoard con curl, agregar un servidor con Python y otro con ionosctl, y verificar la finalización asíncrona de cada uno.
Requisitos previos:
- Cuenta de IONOS CLOUD con un token de API en
IONOS_TOKEN - curl, jq y Python 3 con el paquete
requests ionosctlinstalado (Sección 5.2)
Paso 1: Crear el centro de datos con curl y capturar la URL de la solicitud
RESP=$(curl --silent --dump-header headers.txt --request POST \
'https://api.ionos.com/cloudapi/v6/datacenters' \
--header "Authorization: Bearer ${IONOS_TOKEN}" \
--header 'Content-Type: application/json' \
--data '{"properties": {"name": "taskboard-dev", "location": "de/txl"}}')
export DC_ID=$(echo "$RESP" | jq -r '.id')
export STATUS_URL=$(grep -i '^location:' headers.txt | awk '{print $2}' | tr -d '\r')
echo "$DC_ID $STATUS_URL"
Salida esperada:
<datacenter-uuid> https://api.ionos.com/cloudapi/v6/requests/<requestId>/status
Paso 2: Realizar consultas hasta que el estado sea DONE
until [ "$(curl -s "$STATUS_URL" -H "Authorization: Bearer ${IONOS_TOKEN}" | jq -r '.metadata.status')" = "DONE" ]; do
sleep 5
done; echo "datacenter ready"
Salida esperada:
datacenter ready
Paso 3: Crear un servidor con Python
Guárdelo como create_server.py, reutilizando wait_for_request y call de las secciones 3.1 y 4.1:
import os, requests
API = "https://api.ionos.com/cloudapi/v6"
s = requests.Session()
s.headers.update({"Authorization": f"Bearer {os.environ['IONOS_TOKEN']}",
"Content-Type": "application/json"})
body = {"properties": {"name": "taskboard-api-py", "type": "VCPU",
"availabilityZone": "AUTO", "cores": 1, "ram": 2048}}
resp = call(s, "POST", f"{API}/datacenters/{os.environ['DC_ID']}/servers", json=body)
resp.raise_for_status()
wait_for_request(s, resp.headers["Location"])
print("server ready:", resp.json()["id"])
Salida esperada:
server ready: <server-uuid>
Paso 4: Crear un servidor con ionosctl
ionosctl compute server create --datacenter-id "$DC_ID" --name taskboard-api-cli \
--type VCPU --cores 1 --ram 2GB --wait
Salida esperada:
ServerId Name Type ... State
<server-uuid> taskboard-api-cli VCPU ... AVAILABLE
Paso 5: Compare los resultados
ionosctl compute server list --datacenter-id "$DC_ID" --cols ServerId,Name,Type,Cores,State
Salida esperada:
ServerId Name Type Cores State
<uuid> taskboard-api-py VCPU 1 AVAILABLE
<uuid> taskboard-api-cli VCPU 1 AVAILABLE
Lista de verificación:
- [ ] Centro de datos creado mediante curl y su solicitud llegó a
DONE - [ ] Servidor Python creado y
wait_for_requestse devolvió sin error - [ ] El servidor
ionosctlllegó aAVAILABLEcon--wait - [ ] Ambos servidores muestran el mismo tipo y número de núcleos en el paso 5
Limpieza:
# Deletes the data center and every resource it contains
ionosctl compute datacenter delete --datacenter-id "$DC_ID" --force --wait
Errores comunes
Errores de desarrollo a evitar con el tema de esta unidad:
-
Omitir la consulta del estado de la solicitud
- Problema: Su script crea un centro de datos y de inmediato crea un servidor en él, y luego lee el servidor antes de que exista. La lógica posterior falla o agota el tiempo de espera.
- Por qué ocurre: La respuesta de
202solo significa "aceptada". El centro de datos estáBUSYhasta que su solicitud estéDONE. - Solución: Lea la cabecera
Locationy llame await_for_request()(Sección 3.1) antes de cada operación dependiente, o use--waitenionosctl.
-
Tratar un 202 como éxito
- Problema: El pipeline informa en verde, pero el recurso nunca aparece.
- Por qué ocurre: Los errores de aprovisionamiento solo aparecen en el estado de la solicitud (Sección 3.2).
- Solución: Haga que el trabajo falle cuando el estado de la solicitud sea
FAILED, y registremetadata.message.
-
Codificar de forma fija un token personal de larga duración
- Problema: Un token en una variable de integración continua se filtra, o deja de funcionar cuando expira y nadie sabe quién es su propietario.
- Por qué ocurre: Los tokens se generan con una duración predeterminada de un año, y un token generado bajo una cuenta de administrador personal no está acotado a un solo servicio.
- Solución: Genere el token bajo un subusuario dedicado con privilegios mínimos, establezca una
ttlexplícita y guárdelo en un almacén de secretos.
Resumen
Ahora puede comunicarse con IONOS CLOUD de la misma manera que lo hace cualquier herramienta: generar un token de portador, llamar a la API v6 y esperar a que las solicitudes asíncronas finalicen antes de construir sobre ellas. Su cliente de Python reintenta con retroceso, recorre colecciones paginadas y lee cuerpos de error estructurados. En la Unidad 1.2, Terraform asume este sondeo por usted, y conocerlo aquí le permite depurarlo allí.
Puntos clave:
- La URL base de la API v6 es
https://api.ionos.com/cloudapi/v6; las APIs de DBaaS tienen sus propios hosts regionales - Genere tokens de acceso con
GET /auth/v1/tokens/generate, establezcattly almacene el valor de una sola vez - Una creación devuelve
202junto con un encabezadoLocation; realice el sondeo de/requests/{id}/statushastaDONE - Los errores de validación de detección rápida son síncronos; los errores de aprovisionamiento solo aparecen en el estado de la solicitud
- Use retroceso para
429, y pagine conoffset,limity_links.next
Terminología importante:
- Token de acceso: Un JWT enviado como
Authorization: Bearer <token>; su tiempo de vida se establece conttlen la generación - Estado de la solicitud: El recurso detrás del encabezado
Location; informaQUEUED,RUNNING,DONEoFAILED - BUSY: Estado del recurso que significa que al menos una solicitud de modificación está pendiente; las solicitudes adicionales se encolan
- Validación de detección rápida: Verificaciones síncronas antes de encolar; la API devuelve solo el primer error que encuentra
- depth: Parámetro de consulta (de 0 a 10) que controla cuántos niveles de objetos hijos expande una respuesta
Próximos pasos
Siga aprendiendo: Unidad 1.2: Terraform Provider and Core Patterns
Temas relacionados: