API de base a pro: análisis del curso interactivo Básicos API

Si hay una competencia transversal en la industria actual, es entender APIs. No me refiero solo a saber llamar a un servicio desde Postman: me refiero a comprender cómo se diseña, pública, consume, documenta, opera y asegura una API real. El curso interactivo Básicos API, disponible gratuitamente en GitHub Pages, cubre exactamente ese recorrido, desde el concepto de API como contrato operativo hasta los riesgos del OWASP API Security Top 10.

El curso está pensado para estudiantes de redes, ciberseguridad y administración de sistemas, pero en la práctica le sacarán provecho también desarrolladores backend y frontend, perfiles DevOps y, muy especialmente, quienes trabajamos con inteligencia artificial. Y es que las APIs son el lenguaje de toda integración de IA: los grandes modelos de lenguaje se consumen a través de APIs, los agentes se conectan a herramientas mediante protocolos como MCP (que no deja de ser una capa API), y los webhooks notifican eventos entre sistemas. Quien entiende APIs entiende por dónde entra el tráfico legítimo... y por dónde entran los ataques.

Quien complete el curso saldrá con un modelo mental completo del ecosistema API: sabrá leer y razonar sobre contratos OpenAPI, distinguirá semántica HTTP (métodos, estados, cabeceras), entenderá autenticación y autorización a nivel de objeto, sabrá detectar exposición excesiva de datos, y tendrá una checklist práctica para auditar el diseño y la operación de cualquier endpoint. Todo ello sin instalar nada: basta abrir la página en el navegador.

Anatomía del contenido: recorrido sección a sección

El curso se organiza en secciones encadenadas que van de lo conceptual a lo operativo. Veamos cada una en detalle.

Hero: la API como contrato operativo

La página abre con un modelo mental deliberado: una API es un contrato operativo entre consumidores y capacidades. No es «una URL que devuelve JSON», ni una base de datos publicada. Es un acuerdo con reglas, formatos y expectativas estables que otras personas y programas pueden usar sin conocer la implementación interna. Esta framing es la que sostiene todo el resto del curso: si la API es un contrato, romper el contrato (cambiar campos, significados o permisos sin aviso) es un incidente, no una trivialidad.

Acompaña al hero una franja de datos clave con tres anclas normativas: la versión 3.2.0 de OpenAPI Specification, el RFC 9110 de semántica HTTP y los 10 riesgos del OWASP API Security Top 10. El curso no enseña APIs de oídas: cada afirmación se apoya en fuentes primarias.

El mapa del ecosistema API

La primera sección interactiva es un mapa conceptual construido con Cytoscape.js donde se visualizan 14 componentes del ecosistema API y sus relaciones: cliente, contrato OpenAPI, endpoint y recurso, API Gateway, autenticación y autorización, validación de entrada, handler o controlador, datos y recursos internos, respuesta HTTP, rate limit y paginación, webhooks y asincronía, observabilidad, versionado y deprecación, y amenazas API.

Al hacer clic en cada nodo, un panel lateral muestra la descripción del componente, tres hechos clave y enlaces a las referencias oficiales correspondientes. Las aristas del grafo cuentan la historia completa: el cliente lee el contrato, el contrato describe el endpoint, el cliente llama al endpoint, este entra por el gateway, que aplica autenticación y limita el consumo; la validación entrega al handler, que usa los datos, que alimentan la respuesta, que devuelve al cliente. Y en paralelo, el nodo de amenazas ataca la autenticación, enumera los datos y abusa de los límites: la superficie de ataque dibujada sobre la propia arquitectura.

Algunos detalles que aprecio del contenido de los nodos: el gateway «puede centralizar controles comunes, pero no sustituye autorización en el servicio»; el webhook «también es una API y debe autenticarse, firmarse o verificarse»; y la observabilidad recuerda no registrar nunca tokens completos ni datos personales innecesarios. Son matices que distinguen un curso pensado por alguien que ha operado APIs de un tutorial genérico.

Simulador: de necesidad a respuesta en 9 pasos

La segunda sección es un simulador paso a paso que recorre el ciclo de vida real de una operación API con nueve etapas: caso de uso, contrato, solicitud, gateway, autenticación y autorización, validación, lógica y datos, respuesta, y operación y evolución. Cada paso incluye una descripción, una traza de flujo con los elementos concretos del paso (por ejemplo, en el paso de solicitud: método GET, ruta /api/v1/users/123/orders?limit=20, cabeceras Accept, Authorization y Traceparent) y una lista de comprobaciones.

El caso guía es consistente: consultar los pedidos de un usuario. En el paso de contrato se muestra un documento openapi: 3.2.0 con la operación GET /users/{userId}/orders y sus respuestas 200, 401, 403, 404 y 429: el curso insiste en documentar errores, no solo el caso feliz. En validación advierte que «sintaxis JSON válida no basta» y que hay que evitar mass assignment permitiendo solo propiedades esperadas. En respuesta introduce Problem Details (application/problem+json) y el patrón 429 + Retry-After. En el paso final conecta con producción: métricas de latencia y errores, correlation IDs y traceparent, deprecación antes de breaking changes y pruebas de contrato automatizadas en CI.

Dos comprobaciones del simulador merecen subrayado. En el paso de autenticación distingue 401 de 403 «para mejorar diagnóstico sin filtrar información»: el primero pide credenciales, el segundo indica que la identidad autenticada no tiene permiso, y confundirlos dificulta el soporte de integraciones. En el paso de gateway insiste en que «no delegues toda la autorización en el gateway» y en «registrar trazas sin guardar tokens completos»: decisiones que se toman en minutos y se pagan durante años.

Anatomía técnica: contrato y comportamiento

La tercera sección desmenuza siete piezas de una API mediante un selector interactivo: endpoint, contrato, auth, validación, errores, operación y evolución. Cada pieza tiene su explicación y tres hechos técnicos. Aquí están algunas de las ideas centrales de cada una:

• Endpoint: la ruta debería nombrar recursos (sustantivos) y el método expresar intención; GET /users/{id} es más predecible que POST /getUserById. El path identifica recursos; la query filtra, ordena o página.
• Contrato: OpenAPI convierte la API en una pieza verificable de la que salen documentación, SDKs, mocks y pruebas de compatibilidad. «Un contrato obsoleto es deuda operativa.»
• Auth: identidad no es permiso. La autenticación responde quién llama; la autorización, qué puede hacer sobre qué objeto. Los scopes amplios elevan el impacto de los tokens filtrados, y OAuth 2.0 moderno recomienda PKCE.
• Validación: JSON válido puede seguir siendo negocio inválido. La lista blanca de campos evita mass assignment; los límites de tamaño protegen disponibilidad.
• Errores: diseñados para máquinas. 401 pide autenticación; 403 indica falta de permiso; 409 comunica conflicto; 429 comunica límite. Problem Details evita inventar formatos incompatibles.
• Operación: rate limits, paginación, caché, cuotas, timeouts y trazas convierten un endpoint correcto en un servicio operable. Sin paginación, una colección crece hasta romper clientes o servidores.
• Evolución: añadir campos suele ser compatible; cambiar significado, tipos o permisos puede romper integraciones. Depreca con fecha, alternativa y telemetría de uso.

Laboratorio local: analiza un endpoint

Para mí, la joya del curso. Es un analizador de endpoints que funciona íntegramente en el navegador, sin backend. Describes una operación API: método HTTP (GET, POST, PUT, PATCH, DELETE), ruta, mecanismo de acceso (OAuth 2.0 Bearer con scopes, Bearer simple, API key, mTLS o sin autenticación), estado de respuesta previsto (12 códigos desde 200 hasta 500), cabeceras de respuesta y cuerpo JSON. Al pulsar «Analizar», la aplicación evalúa la operación y emite un informe con hallazgos clasificados en buenos, advertencias y críticos.

El analizador razona de verdad sobre lo que le das. Detecta si la ruta es parseable, si contiene segmentos verbales como get, create o doStuff (diseño menos RESTful), si declara versión (/v1/), si una colección GET prevé paginación (limit, cursor o page), si un POST que crea recursos debería devolver 201 en lugar de 200, si un error 4xx/5xx usa Problem Details, y si el mecanismo de autenticación es fuerte (OAuth 2.0 o mTLS), reutilizable (Bearer simple o API key, con recomendación de rotación y scopes mínimos) o inexistente (crítico).

Además parsea las cabeceras que pegues: comprueba el Content-Type, la presencia de señales de rate limit (RateLimit-Limit, Retry-After o estado 429), trazabilidad (traceparent o x-request-id), y marca como crítico si encuentra X-Debug-Trace o SQL en las cabeceras (exposición de detalle interno), y como advertencia un Access-Control-Allow-Origin: *. Del cuerpo JSON valida la sintaxis con JSON.parse y, si parsea, busca claves sensibles como password, passwordHash, secret, token, accessToken, refreshToken, isAdmin, role, internal o ssn (el patrón clásico de sobreexposición de propiedades), y avisa si un array o una colección data llega sin metadatos de paginación ni links.

Incluye dos perfiles precargados para comparar: «Cargar bueno» (GET versionado y paginado, OAuth 2.0, Content-Type JSON, RateLimit, Link de paginación y traceparent) y «Cargar débil» (POST /api/doStuff?userId=123&admin=true sin autenticación, Content-Type text/plain, CORS abierto, X-Debug-Trace con SQL, y un cuerpo que devuelve passwordHash, role e isAdmin). Analizar ambos perfiles en secuencia es la mejor demostración práctica de la diferencia entre una API diseñada y una API peligrosa.

Checklist de riesgos inspirada en OWASP API Security Top 10

La sección de riesgos presenta 8 señales observables con puntuación ponderada y un panel que calcula el nivel de riesgo acumulado: bajo (menos de 28 puntos), medio (28-59) o alto (60 o más). Las señales son:

• IDs de objeto sin autorización (30 puntos): cambiar un ID permite leer o modificar datos ajenos. Es el BOLA (Broken Object Level Authorization) del OWASP API Top 10, y el consejo es verificar ownership, tenant, rol y scope por objeto, no solo por ruta.
• Autenticación débil o ausente (28): tokens largos, API keys compartidas o endpoints sin auth.
• Exposición excesiva de propiedades (24) y mass assignment (24): devolver o aceptar campos internos que el cliente no necesita o no debería escribir.
• Sin rate limits ni cuotas (22): consumo abusivo que degrada disponibilidad o dispara costes.
• Consumo inseguro de APIs externas (20): confiar en datos o webhooks de terceros sin validar, firmar o limitar.
• Errores con trazas internas (18): stack traces, SQL o secretos que ayudan al atacante.
• APIs sin inventario (16): endpoints antiguos o sombra expuestos sin propietario ni pruebas.

Cada señal marcada muestra además su recomendación de mitigación concreta. Es una mini-auditoría gamificada que puedes aplicar mentalmente a cualquier API que mantengas.

Merece la pena detenerse en cómo puntúa: no todas las señales pesan igual porque no todas se explotan igual. La autorización de objeto rota encabeza la lista con 30 puntos porque es el fallo que directa y silenciosamente filtra datos de terceros; la falta de inventario cierra con 16 porque su riesgo es más difuso. Marcar solo BOLA y auth débil (58 puntos) ya sitúa la API en riesgo medio: el curso enseña a razonar prioridades de remediación, no solo a contar casillas.

Quiz autocorregido

El quiz tiene 8 preguntas de opción múltiple con explicación inmediata tras responder, contador de aciertos y botón de reinicio. Las preguntas cubren el temario completo: qué es una API (contrato, no base de datos publicada), diseño REST coherente (GET /users/{id}/orders frente a POST /getOrders), para qué sirve OpenAPI, la diferencia práctica entre 401 y 403, el RFC 9457 Problem Details para errores estructurados, la señal típica de BOLA (cambiar /orders/123 por /orders/124 y obtener un pedido ajeno), por qué existe la paginación, y el problema N+1 en GraphQL cuando cada campo dispara consultas separadas (con mención a DataLoader y batching como mitigación).

Destaco que la explicación aparece tanto si aciertas como si fallas: el objetivo es consolidar lo aprendido, no la nota.

Guía rápida de repaso

Seis tarjetas resumen el mínimo operativo: 1) define recursos con nombres de dominio, no verbos, y no copies la estructura de la base de datos; 2) respeta HTTP: GET lee, POST crea, PUT reemplaza, PATCH modifica parcialmente, DELETE elimina, y los códigos de estado deben ser útiles para clientes automáticos; 3) pública contrato con ejemplos realistas y esquemas validables; 4) protege objetos autorizando por usuario, tenant y función, sin confiar en IDs del cliente; 5) controla el abuso con rate limits, cuotas, paginación y 429 + Retry-After; 6) observa y evoluciona con trazas, correlation IDs, deprecación antes de romper e inventario de APIs internas, públicas y de terceros.

Glosario y fuentes primarias

El curso cierra con un glosario esencial en formato desplegable (API, endpoint, contrato, scope, Problem Details, idempotencia) y una sección de referencias filtrable por categoría (HTTP, contrato, seguridad, registros) con buscador de texto. La lista incluye 15 fuentes primarias: OpenAPI 3.2.0, los RFC 9110, 9111, 9205, 9457, 8259, 9700 y 6750, JSON Schema 2020-12, la especificación GraphQL de septiembre de 2025, el OWASP API Security Top 10 2023, los registros IANA de métodos, códigos de estado y campos HTTP, y el W3C Trace Context. Es la bibliografía que yo recomendaría a cualquiera en serio: nada de tutoriales de blog, solo especificación.

Mecánica interactiva: cómo está construido

Técnicamente, el curso es una aplicación estática de HTML, CSS y JavaScript plano, sin frameworks, sin npm y sin paso de build: puedes abrir el index.html directamente en tu navegador y funciona. El repositorio público contiene apenas un index.html de 412 líneas, un styles.css, un script.js de unas 1.430 líneas, un README y una imagen del ecosistema API. La única dependencia externa es Cytoscape.js 3.34.1 cargada desde CDN para renderizar el grafo del mapa; si no está disponible, el código incluye un fallback que lista los componentes sin grafo.

El script.js está organizado de forma muy legible: los datos del curso viven en arrays de literales (components con los 14 nodos del mapa, graphEdges con las 17 relaciones, journey con los 9 pasos, parts con las 7 piezas anatómicas, references con las 15 fuentes, riskSignals con las 8 señales, quizzes con las 8 preguntas y los dos perfiles del laboratorio) y debajo, funciones de renderizado que inyectan ese contenido en el DOM. Todo el HTML dinámico pasa por una función escapeHtml, un detalle de higiene apreciable en un curso que, precisamente, enseña a no confiar en la entrada.

El analizador de endpoints es puro JavaScript del lado del cliente: parsea la ruta (incluidas URLs absolutas) con la API URL, extrae cabeceras con un parser propio de líneas Nombre: valor, valida el JSON con JSON.parse en un bloque try/catch y recorre el objeto parseado con una pila para buscar claves sensibles en cualquier profundidad. Ningún dato sale de tu navegador.

Otros detalles de la experiencia: modo claro/oscuro con toggle que se persiste en localStorage (clave basicos-api-theme) y respeta la preferencia del sistema; animaciones de aparición de secciones con IntersectionObserver; navegación accesible con skip-link, roles ARIA y regiones aria-live que anuncian los cambios en los paneles; y diseño responsive verificado en escritorio y móvil.

Por qué importa: APIs, IA y la superficie de ataque

Desde la perspectiva de IAcademy, este curso toca una cuerna central: la inteligencia artificial aplicada no vive en un cuaderno de Jupyter, vive integrada. Cada asistente que escribe en un CRM, cada agente que consulta una base de conocimiento, cada pipeline que llama a un LLM lo hace a través de APIs. Las APIs de los grandes proveedores de modelos son APIs HTTP con claves, límites de consumo, códigos de error y contratos de versión; MCP estandariza cómo un modelo descubre y llama herramientas, que son endpoints; los webhooks devuelven el control a tu sistema cuando un trabajo asíncrono (una generación larga, un fine-tuning) termina. Los conceptos de este curso (scopes mínimos, no registrar secretos, validar entrada, Retry-After, trazabilidad) se aplican uno a uno a esas integraciones.

Y hay una simetría molesta que el curso hace explícita con su nodo de amenazas: las mismas APIs que habilitan la integración habilitan el ataque. Un agente con un token de scopes amplios es exactamente el escenario de «scopes amplios elevan impacto de tokens filtrados». Un endpoint sin autorización de objeto es la fuga de datos que enumera un atacante (o un agente mal configurado) cambiando IDs. El OWASP API Security Top 10 no es una lista teórica: es el mapa de por dónde se rompen los sistemas reales, y este curso lo convierte en señales concretas que puedes marcar y puntuar.

Para el profesional que construye o usa IA, la conclusión práctica es directa: antes de conectar tu agente a esa API tentadora, pasa su diseño por el laboratorio del curso, revisa qué mecanismo de autenticación usa, qué devuelve el cuerpo y qué cabeceras comunica. Treinta minutos de análisis previo evitan incidentes que ninguna demo compensa.

Cómo usarlo: un plan de estudio concreto

El curso se puede recorrer en una sesión de 45-60 minutos, pero propone más valor si lo conviertes en un plan de tres días:

• Día 1: Modelo mental (20-30 min): recorre el mapa del ecosistema haciendo clic en los 14 componentes y leyendo sus hechos clave; luego avanza el simulador de 9 pasos completo, deteniéndote en las comprobaciones de cada paso. Termina con la sección de anatomía para consolidar el vocabulario (contrato, scope, Problem Details, idempotencia).
• Día 2: Manos al laboratorio (30-40 min): carga el perfil «bueno», analízalo y lee cada hallazgo verde; después carga el «débil» y compara los críticos rojos. Como ejercicio final, describe con el formulario un endpoint real de tu propio trabajo o de una API pública que uses, y audita el informe que genera.
• Día 3: Seguridad y consolidación (20-30 min): usa la checklist de riesgos sobre una API que conozcas bien y anota tu puntuación; luego haz el quiz sin mirar y revisa las explicaciones de tus fallos. Cierra leyendo dos referencias de la sección de fuentes: el OWASP API Security Top 10 y el RFC 9457.

Un consejo de estudio: el curso no guarda tu progreso entre sesiones (solo recuerda el tema claro/oscuro), así que tus notas del laboratorio y de la checklist conviene tomarlas aparte. Precisamente por ser una página estática sin cuentas ni telemetría, es un buen recurso para compartir en clase o en un taller interno sin fricción alguna.

Conclusión

Básicos API es un curso honesto: no promete convertirte en arquitecto de APIs en una tarde, pero sí entrega lo que anuncia: un recorrido completo, verificable contra fuentes primarias y con práctica real, desde qué es una API hasta cómo se rompe. Su laboratorio de análisis de endpoints y su checklist puntuada del OWASP API Top 10 lo elevan por encima del típico artículo divulgativo. Para quien trabaja con IA, entender este material no es opcional: es la alfabetización mínima de quien integra, consume y asegura los sistemas por los que hoy circula la inteligencia.

Preguntas frecuentes