Unidad 1.1: IONOS API, Autenticación y Modelo Async

Introducción

Está a punto de crear TaskBoard, una herramienta de gestión de tareas API con una interfaz web, y enviar cada pieza de ella a través del código en IONOS Cloud. No hará clic en el Data Center Designer. Antes de que pueda aprovisionar un solo servidor, necesita tres cosas configuradas correctamente: cómo autenticarse, cómo el API le indica que un recurso está realmente listo, y qué cliente (HTTP crudo, SDK, o CLI) utilizar en cada situación.

Esta unidad es el contrato que firma con el API de IONOS Cloud. El hecho más importante que debe internalizar es que el aprovisionamiento es asíncrono: un POST devuelve inmediatamente con un ID de solicitud, no con un recurso terminado. Trate la respuesta como "aceptado, trabajando en ello" en lugar de "listo", y evitará la clase más común de error de automatización en esta plataforma. Configurará 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. El IONOS Cloud REST API

Cada recurso de TaskBoard que crea, desde el centro de datos hasta el servidor hasta el Load Balancer, pasa por el IONOS Cloud REST API. El Cloud API tiene versiones y se encuentra bajo una sola URL base. Todas las llamadas a CloudAPI apuntan a https://api.ionos.com/cloudapi/v6, y las solicitudes y respuestas son JSON (Content-Type: application/json).

Los recursos se dirigen de manera jerárquica. Un servidor, por ejemplo, se encuentra bajo su centro de datos: /datacenters/{datacenterId}/servers/{serverId}. Este anidamiento es importante porque casi siempre se crea un padre antes que un hijo, y el padre tiene que estar completamente aprovisionado primero (ver Sección 3).

1.1 URL base, versionado y tipos de contenido

La superficie de CloudAPI está fijada en v6 en la ruta. Fíjela explícitamente en su código en lugar de confiar en un alias no versionado, para que un aumento de versión upstream nunca cambie silenciosamente el comportamiento bajo su automatización.

# 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 cuánto del árbol de recursos anidados se devuelve. depth=1 devuelve la colección con propiedades de nivel superior; profundidades más altas incluyen hijos. 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 detalles completos.

1.2 Nota sobre hosts de API separados

No todos los servicios de IONOS 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 conexión desde la documentación de ese servicio en lugar de asumir la base de CloudAPI. El encabezado de autenticación, sin embargo, permanece igual con el token de portador en estos hosts.

2. Autenticación

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

Dos hechos operativos impulsan la elección. Primero, las cuentas con 2FA habilitado o aplicado deben utilizar la autenticación de token de portador. Segundo, la autenticación básica está documentada como que se discontinuará en el futuro cercano y solo debe utilizarse en combinación con 2FA. La conclusión práctica para cualquier nueva automatización es utilizar tokens de portador.

2.1 Tokens de portador a través de la Token Manager

Puede generar tokens a través de la API/SDK Autenticación Token Manager (en la DCD bajo Menú > Administración > Token Manager, a través de la API, o a través de la CLI). Un token es una cadena que coloca en el encabezado 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 generación de tokens, y luego reutilizar ese valor de token para llamadas posteriores a la API y la 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"

Tenga en cuenta que el host de generación de tokens es auth/v1, no cloudapi/v6. El token que obtiene se utiliza luego contra la CloudAPI.

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

La Token Manager impone límites concretos que debe diseñar alrededor. 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 se puede recuperar después; también puede descargarlo como un archivo en ese momento. Capte el token inmediatamente en su tienda de secretos, porque no hay una opción "mostrar de nuevo" más tarde.

Estos límites dan forma a un patrón de mínimo privilegio y rotación amigable. Emite un token separado con TTL corto por servicio y por entorno (uno para la tubería de CI de TaskBoard, uno para el servicio de API en ejecución, etc.) en lugar de compartir un token de larga duración en todas partes. Debido a que los tokens expiran en un TTL fijo, la rotación es una rutina que se automata en lugar de una alarma.

# 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 acuña un token fresco por ejecución agotará su cuota. Acuña una vez, almacene, reutilice hasta la expiración, y luego rote.

3. El modelo de aprovisionamiento asíncrono

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

Debe esperar a que se complete antes de cualquier operación que dependa del nuevo recurso. Adjuntar un Volume a un servidor que todavía está BUSY, o crear una NIC en un centro de datos que está medio aprovisionado, falla. El modelo asíncrono no es opcional, y no es algo que pueda evitarse con reintentos en la llamada dependiente sola.

3.1 La respuesta 202 y el encabezado Location

Cuando crea un recurso, el estado de respuesta es 202 Accepted, el cuerpo contiene el nuevo recurso id, y el encabezado de 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:'

El encabezado Location lleva 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 conexión básicos de Cloud API establece que la respuesta incluye un encabezado Location con una URL para sondear el estado de la solicitud, y el recurso mantiene un estado BUSY hasta que se completa la provisión.

3.2 Sondeo hasta DONE

El punto de conexión de estado informa del estado de la solicitud. Usted sondea hasta que el estado sea DONE (una provisión fallida se presenta como FAILED). Solo entonces procede a operaciones dependientes.

La forma exacta de la carga útil del estado de la solicitud y el ritmo de sondeo recomendado a continuación reflejan la práctica de automatización común de IONOS en lugar de un extracto de documentación literal. Los valores de estado BUSY, DONE y FAILED están basados 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 SDKs envuelven este bucle para usted. Pase la opción SDK que espera la finalización y el cliente realiza sondeos internamente, por lo que el código de su aplicación se lee como si la llamada fuera síncrona, mientras sigue respetando el modelo asíncrono subyacente.

4. SDKs y la CLI de ionosctl

No escribirá código raw curl para la lógica de la aplicación. IONOS 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 autenticarán con el mismo token de portador y todos deben cumplir con el modelo asíncrono.

4.1 El SDK de Python

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

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

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 la vida útil de ese objeto vinculada al TTL del token y refrésquelo cuando lo rote.

4.2 La CLI de ionosctl

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

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

La siguiente tabla compara las cuatro formas en que interactúa con el IONOS Cloud API para que pueda elegir deliberadamente en lugar de por costumbre.

Como se muestra arriba, use el SDK para la lógica de aplicación, ionosctl para tareas rápidas y pegamento de CI, raw HTTP cuando esté depurando el protocolo en sí, y Terraform (siguiente unidad) para todo lo que debería vivir como estado declarativo.

5. Límite de tarifa, paginación y control de errores

La automatización de producción enfrenta tres realidades que los ejemplos de camino feliz pasan por alto: el API limita su tarifa, las colecciones están paginadas y algunos códigos de error significan algo diferente a lo que usted espera.

5.1 Límite de tarifa con retroceso exponencial

Cuando usted excede la tarifa de solicitudes, el API responde con 429. La respuesta correcta es retroceder exponencialmente y volver a intentarlo, no golpear el punto de conexión.

La implementación de retroceso exponencial a continuación es un patrón de reintento estándar del lado del cliente; la semántica de estado 429 está basada en la documentación, los retrasos y la perturbación específicos son una elecció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 de conexión de la 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 de conexión de la 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 obtuvo exactamente limit elementos, casi con certeza hay otra página.

5.3 Manejo de errores y la trampa del 404

El error que usted malinterpretará primero es 404 durante la provisión. Un 404 inmediatamente después de crear un recurso generalmente significa que el recurso aún no está listo, no que esté faltando. Esto es el modelo asíncrono que le está afectando: usted saltó la encuesta y consultó un recurso secundario antes de que su recurso principal 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)

Lea los cuerpos de respuesta en caso de error. Las respuestas de error de IONOS incluyen una carga útil estructurada con el código HTTP y un mensaje legible para humanos; regístrelo en lugar de tragar la excepción, para que un 429, un cuerpo mal formado (422) y un fallo de autenticación (401) sean inmediatamente distinguibles en la salida de su pipeline.

API Tarjeta de referencia rápida

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

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

Laboratorio de código

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

Requisitos previos:

• Cuenta de IONOS Cloud con acceso a API
• curl, python3, y ionosctl instalados localmente
• El ionoscloud Python SDK: 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 una consulta hasta que el centro de datos esté TERMINADO

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 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)

Salida esperada:

sdk server: <server-id>

Paso 6: Crear un servidor mediante 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 manera fija
• [ ] El centro de datos alcanzó el estado DONE antes de que se creara cualquier servidor
• [ ] Tres servidores creados mediante 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 provisión como síncrona

   • Problema: Su script crea un servidor y adjunta inmediatamente un Volume, obteniendo un error intermitente 404 o un error de conflicto.
   • Por qué sucede: El POST devolvió 202 Accepted con el recurso en estado BUSY; el recurso aún no está listo.
   • Solución: Realizar una consulta al URL de estado desde el encabezado Location hasta DONE, o utilizar la opción de espera de finalización del SDK, antes de cualquier llamada dependiente.

2. Crear un token fresco en cada ejecución

   • Problema: Un trabajo programado deja de funcionar después de un tiempo con errores de autenticación, y encuentra decenas de tokens en el Token Manager.
   • Por qué sucede: Cada usuario tiene un límite de 100 tokens; un script que genera uno por ejecución agota el cupo y pierde la pista de qué token está activo.
   • Solución: Generar un token con ámbito por servicio/entorno, almacenarlo en una tienda de secretos, reutilizarlo hasta que expire su TTL, luego rotarlo. El valor del token se muestra solo una vez, así que captúrelo en el momento de su creación.

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

   • Problema: Una operación de lista omite silenciosamente los recursos más allá de los primeros 1000 elementos.
   • Por qué sucede: Los puntos de conexión de la colección paganinados con un limit predeterminado de 1000; el código que ignora offset/limit ve una página.
   • Solución: Realizar un bucle con offset creciente hasta que una página devuelva menos de limit elementos (ver Sección 5.2).

Resumen

Ahora usted tiene el contrato en el que dependen todas las unidades posteriores. Puede autenticar con un token de portador desde el Token Manager, respetar el modelo de aprovisionamiento asíncrono mediante la consulta de requests/{id}/status hasta DONE, y aprovisionar el mismo recurso a través de curl, el Python SDK, y ionosctl. También puede mantener la automatización viva bajo carga retrocediendo en 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 manera 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 se vuelve 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 se está discontinuando y las cuentas de 2FA deben utilizar tokens de portador); un usuario puede tener hasta 100 tokens, cada uno con un TTL fijo desde 1 hora hasta 365 días.
• El valor de un token se muestra exactamente una vez y no se puede recuperar, así que caṕtúrelo en el momento de su creación; puede descargarlo como un archivo en ese momento.
• Un 404 justo después de la creación suele significar "no listo aún", no "faltante"; maneje 429 con retroceso exponencial y pagine las colecciones con offset/limit (límite predeterminado 1000).

Terminología importante:

• Token de portador: Una credencial de cadena emitida por el Token Manager, enviada en el encabezado Authorization: Bearer, y el método de autenticación principal para el IONOS Cloud API.
• Modelo de aprovisionamiento asíncrono: El comportamiento de la plataforma donde las llamadas de creación/actualización devuelven 202 y una URL de estado Location; el recurso está BUSY hasta que el aprovisionamiento alcanza DONE.
• Punto de conexión de estado de solicitud: /cloudapi/v6/requests/{id}/status, consultado para saber si una operación asíncrona está BUSY, DONE, o FAILED.
• TTL del token: El tiempo de vida fijo elegido en el momento de la creación del token (1 hora a 365 días) que impulsa su programa de rotación.
• Paginación (desplazamiento/límite): Parámetros de puntos de conexión de colección donde limit limita los elementos por página (predeterminado 1000) y offset establece el índice de inicio.

Próximos pasos

Continúe aprendiendo: Unidad 1.2: Terraform Provider and Core Patterns

Temas relacionados:

• Unidad 1.2: Terraform Provider and Core Patterns
• Unidad 1.3: Verificación de conocimientos - Fundamentos programáticos