APIs REST y JSON: la base de la automatización

📋 En esta lección

Todo lo que automatiza redes — Ansible, controladores, tus futuros scripts, la IA operativa — habla el mismo idioma: peticiones REST con datos en JSON. Aquí aprendes a leer y construir ese idioma: verbos HTTP y su mapeo CRUD, anatomía de una petición y una respuesta, códigos de estado, autenticación — y JSON hasta el nivel de interpretar cualquier salida que te pongan delante.

Qué es una API

Una API (Application Programming Interface) es la puerta por la que software habla con software: el contrato que define qué se puede pedir, cómo, y qué se recibe. Frente a la CLI — diseñada para humanos, con salidas para leer (y frágiles de parsear) — la API entrega datos estructurados que un programa consume sin ambigüedad.

La consecuencia para redes: el show interfaces que tú lees con los ojos, un script lo pide a la API y recibe cada campo (nombre, estado, errores) como dato individual, listo para comparar, alertar o graficar. La API northbound de un controlador (11.2) es exactamente esto.

REST: las reglas del juego

REST es el estilo de API dominante — el de los controladores Cisco, y el de media Internet. Sus principios prácticos:

• Todo es un recurso con URL: https://controlador/api/v1/devices/switch-01/interfaces — la jerarquía de recursos se lee como un sistema de archivos.
• Los verbos HTTP dicen la acción — el mapeo CRUD que el examen pregunta:

• Sin estado (stateless): cada petición es autocontenida — lleva su autenticación y todo su contexto; el servidor no recuerda la anterior. (El mismo sentido de "stateless" que en las ACLs — 10.5: sin memoria entre eventos.)
• Datos en JSON (normalmente): la carga útil de ida y vuelta.

Anatomía de una petición y su respuesta

GET /api/v1/devices/switch-01/interfaces/Gi0-1 HTTP/1.1
Host: controlador.empresa.local
Authorization: Bearer eyJhbGciOi...          ← el token de autenticación
Accept: application/json                     ← "respóndeme en JSON"

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name": "GigabitEthernet0/1",
  "status": "up",
  "vlan": 10,
  "errors": { "crc": 0, "late_collisions": 0 }
}

Los códigos de estado — la primera lectura de toda respuesta:

El par 401/403 merece precisión: 401 = "¿quién eres?" (credenciales ausentes o inválidas); 403 = "sé quién eres, y no puedes" (autenticación OK, autorización no — las dos Aes de la 10.3, en versión API).

Autenticación: desde el básico usuario/contraseña por petición hasta el patrón dominante — obtienes un token (a menudo con caducidad) autenticándote una vez, y lo presentas en cada petición (Authorization: Bearer …). Como todo viaja por HTTPS, el token no se expone — y como el token es la llave, se trata como una contraseña (no se commitea a Git: el incidente clásico).

JSON: el formato que hay que leer con fluidez

JSON (JavaScript Object Notation) es texto estructurado con cuatro reglas:

1. Objeto { }: pares "clave": valor, separados por comas.
2. Array [ ]: lista ordenada de valores.
3. Valores posibles: cadena ("texto", siempre con comillas dobles), número (sin comillas), true/false, null — u otro objeto o array (anidamiento).
4. Las claves, siempre entre comillas dobles.

{
  "hostname": "SW-ACCESO-01",
  "uptime_days": 214,
  "managed": true,
  "location": null,
  "vlans": [10, 20, 30],
  "interfaces": [
    { "name": "Gi0/1", "status": "up",   "vlan": 10 },
    { "name": "Gi0/2", "status": "down", "vlan": 10 }
  ]
}

Leerlo como el examen exige: vlans es un array de números; interfaces es un array de objetos — interfaces[1].status vale "down" (los arrays cuentan desde 0). true sin comillas es booleano; "true" con comillas sería una cadena — distinción que las preguntas explotan. Y null es "sin valor", distinto de 0 y de "".

(Los parientes que basta reconocer: XML — el formato veterano, más verboso, que usa NETCONF — y YAML — el formato amable en el que escribirás Ansible en la próxima lección: mismo modelo de datos, sintaxis por indentación.)

El puente a los equipos: RESTCONF y NETCONF

Los propios equipos IOS-XE exponen APIs: RESTCONF (REST+JSON sobre HTTPS, contra modelos de datos YANG — pedir .../interfaces/interface=GigabitEthernet0%2F1 devuelve la configuración como JSON) y NETCONF (el veterano: XML sobre SSH, transaccional). Para el CCNA: saber que existen, qué transporte y formato usa cada uno, y que ambos operan sobre modelos YANG — la configuración como datos estructurados en vez de texto de CLI.

! Habilitar RESTCONF en IOS-XE (con HTTPS y un usuario — 10.2):
R1(config)# restconf
R1(config)# ip http secure-server

Probarlo tú: curl y Postman

Las herramientas del oficio: Postman (GUI para construir y guardar peticiones — el laboratorio de APIs) y curl (la navaja de terminal):

$ curl -k -u admin:Clave123 \
    -H "Accept: application/yang-data+json" \
    https://10.9.250.1/restconf/data/ietf-interfaces:interfaces

Diez minutos de curl contra un router de lab (o los sandboxes gratuitos de Cisco DevNet) convierten esta lección de teoría en músculo.

Relación con otros conceptos

• Esta es la API northbound de la 11.2 en detalle; Ansible (11.4) la consumirá por ti — y sus inventarios/playbooks usan YAML, el primo de JSON.
• HTTPS/TLS que protege todo esto: 1.6 y 10.7; el par 401/403 es AAA (10.3) hablado en HTTP.
• Los datos estructurados que devuelven estas APIs son el alimento de la telemetría y la IA operativa (11.6-11.7).
• RESTCONF/NETCONF sobre YANG son los protocolos southbound modernos del mundo SDN (11.5).

Resumen

Las APIs son software-a-software con datos estructurados — adiós al parseo frágil de salidas de CLI. REST: recursos con URL + verbos HTTP mapeando CRUD (POST-crear, GET-leer, PUT/PATCH-actualizar, DELETE-borrar), stateless (cada petición autocontenida, autenticación incluida — típicamente token Bearer sobre HTTPS), respuestas con códigos (2xx éxito; 4xx error del cliente — 401 sin autenticar vs 403 sin permiso; 5xx del servidor). JSON: objetos {"clave": valor}, arrays [...], cadenas con comillas dobles, números/booleanos/null sin ellas, anidamiento libre — leerlo con fluidez es requisito de examen. Y los equipos también hablan: RESTCONF (JSON/HTTPS) y NETCONF (XML/SSH) sobre modelos YANG. Practica con curl/Postman: es la puerta de todo el módulo.

Fuentes oficiales

• RFC 9110 — HTTP Semantics (métodos y códigos de estado)
• RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format
• RFC 8040 — RESTCONF Protocol