Módulo 04Trimestre 1 · Fundamentos4 puntos del póster

APIs y contratos

Inicia sesión para guardar tu progreso en todos tus dispositivos. Mientras tanto, se guarda en este navegador.

Por qué importa

Una API es una promesa. En cuanto una app móvil, un partner o un agente depende de ella, cada cambio puede romperle algo a alguien que no ves. Los compradores enterprise te juzgan por la calidad de tus contratos de API.

Resultados de aprendizaje

  1. Diseñar APIs REST coherentes con un contrato OpenAPI.
  2. Hacer idempotente cada endpoint que modifica datos.
  3. Versionar APIs y librerías sin romper a los clientes.
  4. Saber cuándo gRPC es la herramienta adecuada.

Lecciones

4.1 Diseño contract-first

  • Escribe primero la especificación OpenAPI; genera a partir de ella los tipos, los clientes, la documentación y los servidores mock.
  • Convenciones coherentes: sustantivos para los recursos, rutas en plural, códigos de estado estándar, paginación por cursor, timestamps en ISO 8601.
  • Un único formato de error en todas partes (RFC 9457 Problem Details): type, title, status, detail, más un ID de solicitud.
  • Valida cada entrada contra el esquema en la frontera; rechaza los campos desconocidos.
  • Nunca devuelvas más campos de los necesarios (la exposición excesiva de datos es una vulnerabilidad clásica de las APIs).

4.2 Idempotencia (14)

Las redes fallan después de que el servidor hizo el trabajo, pero antes de que el cliente reciba la respuesta. El cliente reintenta. Sin idempotencia, al cliente se le cobra dos veces.

Patrón (popularizado por Stripe):

  1. El cliente envía Idempotency-Key: <uuid> en el POST.
  2. El servidor guarda la clave + el hash de la solicitud + la respuesta en una tabla con una restricción única.
  3. Si llega la misma clave otra vez: devuelve la respuesta guardada, no vuelvas a ejecutar.
  4. Misma clave con un cuerpo distinto: rechaza con 422.
  5. Haz que las claves expiren a las 24 horas o más.

GET, PUT y DELETE deberían ser idempotentes por naturaleza. Diséñalos así.

4.3 Versionado (102, 103)

  • Versionado de APIs: en la URL (/v1/) o en una cabecera. Los cambios aditivos (campos opcionales nuevos) no rompen nada; eliminar o renombrar campos, o cambiar tipos o semántica, sí rompe.
  • Política de deprecación: anúncialo, añade las cabeceras Deprecation y Sunset, mide el uso de la versión antigua y luego elimínala.
  • Versionado semántico para paquetes: MAJOR.MINOR.PATCH. MAJOR rompe, MINOR añade, PATCH corrige. Fija las dependencias con un lockfile; no confíes en que los demás sigan semver al pie de la letra.

4.4 gRPC (100)

Tipado, binario, rápido, con streaming, sobre HTTP/2. Excelente para el tráfico interno entre servicios a escala. Mala opción para navegadores y APIs públicas. Un fundador en solitario rara vez lo necesita; aprende el concepto.

4.5 Avance de seguridad de APIs

Autorización en cada objeto (BOLA es el principal riesgo de las APIs), rate limits por clave, límites de paginación, límites de tamaño de solicitud. Se detalla en 05 · Seguridad de aplicaciones: OWASP Top 10:2025.

Lab 4: Publica un contrato

  1. Escribe una especificación OpenAPI para tu recurso principal; genera un cliente tipado.
  2. Añade idempotency keys a tu endpoint de pago o de "crear pedido"; escribe una prueba que envíe la misma solicitud 5 veces de forma concurrente y verifique que se crea un solo registro.
  3. Haz un cambio incompatible de la forma correcta: publica la v2 junto a la v1 con cabeceras de deprecación.
  4. Pruebas de contrato en la CI que fallen si la implementación se desvía de la especificación.

Definition of Done

Pack de prompts para la IA

  • "Genera una especificación OpenAPI 3.1 a partir de estas rutas y después enumera las incoherencias en nombres, códigos de estado y formatos de error."
  • "Añade idempotency keys al estilo de Stripe a este endpoint, respaldadas por una tabla de Postgres con una restricción única. Maneja el caso de duplicados concurrentes."