Software Architecture
Explica cómo diseñar y evolucionar contratos de API con semántica estable, compatibilidad, deprecación, errores, idempotencia y pruebas de contrato.
Una API es un contrato de comportamiento, no una lista de endpoints. Incluye semántica, identidad, errores, idempotencia, consistencia, límites, compatibilidad y ciclo de vida.
Una API permite que un consumidor use una capacidad sin conocer internals.
consumer
→ contrato estable
→ providerLa estabilidad no significa ausencia de cambios. Significa evolucionar sin romper consumidores inesperadamente.
Qué puede solicitarse y con qué intención.
Campos, tipos, unidades, timezone, nulabilidad y significado.
Estados de éxito, rechazo de negocio y fallo técnico.
Timeouts, asincronía, consistencia y estados pendientes.
Autenticación, autorización, tenant y alcance.
Paginación, rate limits, tamaño y cuotas.
Compatibilidad, versión, deprecación y soporte.
Un endpoint debería expresar una capacidad, no exponer tablas.
POST /orders/{id}/confirmpuede ser más preciso que:
PATCH /orders/{id} { status: "confirmed" }El primero permite validar transición, identidad e idempotencia. El segundo parece permitir cambiar estado arbitrariamente.
Una respuesta útil distingue categorías:
{
"type": "https://nicoo.dev/problems/insufficient-stock",
"title": "Insufficient stock",
"status": 409,
"detail": "Product p-42 has only 2 units available",
"instance": "/orders/o-10/confirm",
"requestId": "req-99"
}No expongas stack traces ni errores del ORM. Tampoco conviertas todo en 500.
Crear pagos, pedidos o reservas puede repetirse por timeout.
Idempotency-Key
+ actor
+ operación
+ hash del payload
→ resultado persistidoUna repetición con la misma intención devuelve el resultado previo. Reutilizar la clave con payload distinto debe rechazarse.
Simple, pero cambios concurrentes pueden producir duplicados o saltos; grandes offsets son costosos.
Usa una posición estable:
createdAt + idNecesita orden determinista y cursor opaco. Define comportamiento si el recurso cambia entre páginas.
Una respuesta debe aclarar qué representa.
202 Accepted
→ operación registrada
→ resultado todavía pendienteNo devuelvas éxito final cuando solo encolaste trabajo.
Para read-your-writes, puedes devolver el nuevo estado directamente o permitir consultar una operación.
Cambios aditivos, campos opcionales y nuevos endpoints pueden mantenerse en la misma versión si consumidores son tolerantes.
Ruta, header o media type. Cada estrategia tiene tooling y visibilidad distintos.
Versionar no evita migrar. Mantener versiones permanentes aumenta superficie y pruebas.
null por ausencia.Un schema aditivo puede ser semánticamente incompatible.
Para datos, puede requerir doble lectura, backfill o versiones.
Los consumidores publican expectativas verificables. El provider ejecuta esos contratos antes de desplegar.
Aportan detección temprana, pero no prueban:
También requieren disciplina si cruzan equipos o despliegues. Un API “privada” puede tener más consumidores de los conocidos.
Mantén catálogo, owner, documentación y telemetría de uso.
Request:
POST /orders/o-42/confirm
Idempotency-Key: confirm-o-42-v1
Authorization: Bearer ...Resultados:
200 confirmed: ya estaba confirmado por la misma intención.409 invalid-state: no puede confirmarse.409 insufficient-stock: rechazo de dominio.202 pending: resultado externo desconocido.401/403: identidad o autorización.429: cuota.El contrato debe documentar qué respuestas pueden reintentarse.
El cliente necesita:
Retry-After para límites.El provider no puede garantizar que un timeout signifique que no ejecutó la operación.
Son APIs asíncronas y requieren:
Responder rápido y procesar de forma segura.
El ID enviado por cliente no demuestra acceso.
Mide por endpoint y consumidor:
Sin telemetría no sabes cuándo retirar una versión.
Define periodo realista y contacto. No elimines basado solo en ausencia reciente si el uso es estacional.
La ausencia debe tener semántica explícita; no uses defaults ambiguos.
Consumers deben manejar fallback o error controlado.
Tenant se deriva de identidad; no se acepta ciegamente del payload.
Define atomicidad parcial, errores por item, límite e idempotencia.
PATCH status puede debilitar invariantes?202 Accepted?Ownership de datos y arquitectura de persistencia conecta contratos con fuentes de verdad, modelos y migraciones.