Diseño y Operación de APIs REST

Curso de nivel avanzado orientado a profesionales que ya consumen e implementan APIs REST con autenticación y quieren dar el salto al diseño, documentación y operación de APIs en entornos reales. El punto de partida es el dominio de los mecanismos de autenticación y la integración de APIs en código; el objetivo es aplicar criterios de diseño profesional: modelar recursos con convenciones REST correctas, documentar contratos con OpenAPI 3.x, gestionar la evolución de la API sin romper clientes existentes, construir suites de tests sistemáticas, optimizar el rendimiento con caché HTTP y paginación eficiente, e integrar notificaciones en tiempo real con webhooks verificados con HMAC. Al finalizar, el participante será capaz de diseñar, documentar, probar y operar una API REST de calidad de producción.

Al finalizar el curso, el participante será capaz de:

• Diseñar los recursos de una API REST aplicando convenciones de nomenclatura con sustantivos en plural, verbos HTTP correctos para cada operación y códigos de estado apropiados para cada escenario de éxito y error
• Documentar una API REST con especificación OpenAPI 3.x, incluyendo esquemas de request/response reutilizables en components/schemas, códigos de error posibles y la sección de autenticación con Bearer token definida en components/securitySchemes
• Diseñar una estrategia de versionado de API que permita evolucionar la API sin romper los clientes existentes, distinguiendo los cambios breaking de los que no lo son y documentando el plan de migración y deprecación
• Implementar tests sistemáticos de una API REST cubriendo el happy path, casos de error (4xx) y casos límite, con criterio explícito de selección de los casos de prueba y herramientas de mocking HTTP
• Optimizar el rendimiento de una API implementando caché HTTP con ETag o Last-Modified y diseñando una estrategia de paginación con cursor para colecciones grandes que evita los problemas del limit/offset convencional
• Diseñar e implementar la integración con webhooks, definiendo el contrato del evento, implementando el endpoint receptor con verificación de firma HMAC y manejando los reintentos y fallos de forma robusta

1. Diseño de recursos REST Convenciones de nomenclatura: sustantivos en plural, minúsculas y guiones; verbos HTTP y su semántica: GET (lectura segura e idempotente), POST (creación o acción), PUT (reemplazo completo idempotente), PATCH (modificación parcial), DELETE (eliminación idempotente); anti-patrones frecuentes: verbos en la URL (/createOrder, /getUser), mezcla de singulares y plurales, códigos de estado incorrectos; códigos de estado apropiados para cada escenario: 200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500; diseño de URLs para recursos anidados y relaciones; acciones que no encajan en CRUD: convenciones para sub-recursos y endpoints de acción

2. Documentación con OpenAPI 3.x Estructura de un fichero OpenAPI 3.x: openapi, info, paths, components, security; definición de endpoints en paths: método, parámetros de ruta y query, cuerpo de petición, respuestas; esquemas reutilizables en components/schemas y referencia con $ref; esquemas de seguridad en components/securitySchemes: type: http, scheme: bearer, bearerFormat: JWT; aplicación de seguridad global y por endpoint; herramientas: Swagger Editor para validación y preview; marcado de campos deprecated con deprecated: true

3. Versionado y evolución de APIs Breaking changes vs non-breaking changes: qué rompe a los clientes y qué no; casos de breaking change: eliminar o renombrar campos, cambiar tipos de datos, modificar semántica de endpoints existentes; casos no breaking: añadir campos opcionales, añadir endpoints nuevos; estrategias de versionado: URL (/v1/) vs cabecera Accept; período de transición: convivencia de versiones en paralelo, comunicación de deprecación, criterios para retirar una versión; documentación de deprecación en OpenAPI; planes de migración para clientes: changelogs y guías de actualización

4. Testing sistemático de APIs Pirámide de tests para APIs: unitarios, integración, E2E; criterios de selección de casos de prueba: clases de equivalencia (éxito, validación, autenticación, servidor, rate limiting); cobertura mínima: happy path, errores de validación (400/422), autenticación fallida (401), servicio no disponible (503), rate limit (429 con Retry-After); herramientas de mocking HTTP en Python: responses, httpretty, pytest-httpserver; uso en CI/CD: rapidez, determinismo, sin dependencias externas; diferencia entre mock de servidor HTTP y mock de función

5. Caché HTTP y paginación eficiente Caché de validación con ETag: el servidor genera un hash del contenido, el cliente lo devuelve con If-None-Match y el servidor responde 304 Not Modified si no ha cambiado; caché con Last-Modified e If-Modified-Since: mismo flujo con timestamp; diferencia entre caché de validación (round-trip al servidor) y caché de expiración (Cache-Control: max-age); problema de rendimiento de OFFSET en tablas grandes: O(N) creciente; paginación con cursor: campo next_cursor en la respuesta, consulta WHERE id > cursor eficiente con índice; índice necesario en la columna del cursor

6. Webhooks con HMAC Diferencia entre polling y webhooks; contrato de un webhook: método POST, payload JSON tipado por evento, cabecera de firma; verificación de autenticidad con HMAC-SHA256: clave secreta compartida, cálculo sobre el cuerpo raw, comparación en tiempo constante (hmac.compare_digest) para evitar timing attacks; patrón "acknowledge fast, process async": responder 200 OK inmediatamente y encolar el procesamiento en background; idempotencia con tabla de IDs de webhooks procesados; respuestas HTTP según escenario: 200 (recibido), 400/401 (firma inválida), 200 (ya procesado), 500/503 (error interno — el emisor reintentará)

• Python 3.x instalado con pip: requests, pytest, responses
• Editor de código (VS Code recomendado)
• Terminal: bash, zsh o PowerShell
• Cuenta en Swagger Editor (online, sin instalación) para validación de especificaciones OpenAPI
• Postman o Bruno para pruebas manuales de endpoints
• Acceso a una API pública con soporte de webhooks para los ejercicios de integración (GitHub Webhooks recomendado, con ngrok o similar para recibir webhooks en local)

→ API02 — Autenticación en REST APIs con Python (Intermedio, 6h)

• Distinguir los mecanismos de autenticación más habituales (API Key, Bearer token, OAuth 2.0) y seleccionar el adecuado según el caso
• Almacenar credenciales en variables de entorno con python-dotenv y configurar .gitignore para evitar filtrarlas
• Implementar peticiones autenticadas con API Key y Bearer token usando la librería requests
• Gestionar errores de autenticación (401) y autorización (403) con acción correcta según el código de estado