En 06-02 comparamos el diseño de Tienda Aroma con el de CafeSocial y cerramos con una tesis incómoda: no existe un diseño REST universal. Ahora llega el último asunto, el que separa una API bien diseñada de una API que sigue viva a los tres años: qué ocurre después de publicarla. Porque el día del lanzamiento la API es tuya; a partir de la primera integración es de tus consumidores, y cada campo que devuelves se convierte en una promesa. Esta lección recorre los tres primeros años de la API de Tienda Aroma como una línea temporal con hitos concretos: el primer incidente, el post-mortem de la caída de Navidad, la deuda de contrato que se va acumulando, la migración a v2 con su calendario de doce meses y el trabajo silencioso de mantenimiento que nadie ve pero que sostiene todo lo demás.

1. La línea temporal de una API en producción
2. El primer día: qué se vigila y qué es normal
3. Gestión de incidentes: severidades, mitigación y comunicación
4. El post-mortem sin culpables (documento completo)
5. Escuchar a los consumidores
6. La deuda de contrato
7. Añadir sin romper: catálogo de cambios seguros
8. Cuándo toca una v2 y cómo se migra en 12 meses
9. Retirar funcionalidades y el coste de lo que casi nadie usa
10. Mantenimiento continuo: dependencias, secretos, SLO y coste
11. Inventario de APIs y APIs zombis
12. Gobierno con varios equipos
13. Errores comunes, ejercicios y conclusión

Conviene ver el ciclo completo antes de entrar en cada hito. Estos son los momentos que marcaron los tres primeros años de https://api.tiendaaroma.example/v1.

Ninguno de estos hitos es un proyecto nuevo: todos son mantenimiento. Y el mantenimiento consume, en una API con varios consumidores externos, bastante más esfuerzo acumulado que la construcción inicial.

El mes 0 la API se publica con dos consumidores propios: la SPA https://tiendaaroma.example y el panel interno. Todo el instrumental que montamos en 04-07 (pino para logs estructurados, prom-client para métricas, trazas con OpenTelemetry, /salud/vivo y /salud/listo) deja de ser un ejercicio y pasa a ser el único sitio donde se puede mirar.

Las cuatro señales que se vigilan desde el minuto uno son las clásicas de un servicio de petición-respuesta:

Y hay una quinta señal que casi nadie mira el primer día y que resulta ser la más informativa: la distribución de los 4xx.

Salida real del segundo día:

Qué es normal y qué no. Los 401 son normales: la SPA reintenta con el token caducado y renueva. Los 404 sobre /cafes/{id} también: hay enlaces antiguos indexados. Lo que no es normal son 412 parametro_invalido en GET /v1/cafes: eso no es un cliente torpe, es un contrato mal explicado. Al inspeccionar los detalles del error aparece el patrón: los clientes envían ?tueste=Medio con mayúscula inicial, y nuestro enumerado sólo acepta claro|medio|oscuro. La documentación lo decía; el mensaje de error, no. Se corrigió el mensaje —no la validación— y los 400 cayeron a 20 al día.

Regla del primer día: un error 4xx repetido no acusa al cliente, describe un defecto de diseño o de documentación de tu API.

El primer incidente (mes 2). Con el lanzamiento de Aroma Móvil aparecen los primeros 429. La app hace polling del carrito cada 5 segundos y el rate limiting de 04-04 empieza a devolver limite_peticiones con Retry-After. El diagnóstico tardó veinte minutos porque las cabeceras Aroma-RateLimit-Restantes no se estaban registrando en los logs. La solución no fue subir el límite: fue añadir ETag al carrito (ya lo teníamos en /cafes, ver 04-05) para que el polling respondiera 304 Not Modified a coste casi nulo, y publicar en la guía de integración que el intervalo recomendado era de 30 segundos.

En 04-07 fijamos un SLO de disponibilidad del 99,9 % mensual para las rutas de lectura. Ese 0,1 % son 43 minutos de presupuesto de error al mes. El presupuesto es lo que convierte una discusión de opiniones ("¿esto es grave?") en una decisión aritmética: si en tres días se ha consumido el 60 % del presupuesto mensual, se congelan los despliegues de funcionalidad y el equipo se dedica a fiabilidad hasta que la tasa se recupere.

Las alertas no se disparan sobre umbrales instantáneos, sino sobre velocidad de consumo del presupuesto (burn rate): consumir el presupuesto 14 veces más rápido de lo sostenible durante 5 minutos es un aviso inmediato; 6 veces más rápido durante una hora, un aviso normal.

Es la regla más difícil de interiorizar para un equipo técnico, porque la curiosidad empuja hacia el por qué. Durante un incidente, el orden correcto es:

1. Restaurar el servicio con lo que sea: revertir el último despliegue, apagar la feature flag (05-04), devolver el tráfico al color anterior en el blue-green, degradar una funcionalidad.
2. Preservar evidencias: capturar trazas, Aroma-Traza-Id de peticiones fallidas, salida de EXPLAIN, métricas del intervalo.
3. Después, entender la causa raíz con calma.

Un despliegue revertido en 4 minutos cuesta un post-mortem; un despliegue depurado en caliente durante 40 minutos cuesta el presupuesto de error del trimestre.

Con consumidores externos —RápidoEnvíos y CataBox—, callar es peor que equivocarse. El patrón que adoptamos: una entrada en la página de estado en menos de 15 minutos aunque no se sepa nada ("estamos investigando errores en la creación de pedidos"), actualizaciones cada 30 minutos, y una nota final con el enlace al post-mortem cuando esté publicado. Nada de detalles internos de infraestructura; sí el impacto observable y el consejo de reintento.

Mes 7, 18 de diciembre. La campaña de Navidad multiplica el tráfico por seis. Dos semanas antes se había añadido el filtro ?origen= a GET /v1/cafes —un cambio retrocompatible de manual, tres líneas de código— pero sin índice en la columna correspondiente. Con el catálogo crecido y el tráfico de campaña, la base de datos se satura y la API queda inaccesible 34 minutos.

Este es el documento tal como quedó en docs/incidentes/. Fíjate en lo que no contiene: ningún nombre asociado a la causa.

La verificación de la acción 1, para que quede claro qué se comprueba:

Sin culpables no significa sin responsables. Las acciones tienen dueño y plazo; la causa no tiene dueño. La persona que añadió el filtro sin índice hizo lo que el sistema le permitía hacer: no había checklist, ni prueba de carga, ni alerta. El sistema falló, y el sistema es lo que se arregla.

A partir del mes 9, la pregunta deja de ser "¿funciona?" y pasa a ser "¿qué están haciendo realmente con ella?". Tres fuentes:

Analítica de uso por endpoint y por cliente. Cada token JWT lleva un client_id (04-02). Se etiqueta la métrica de peticiones con ese identificador, pero con cuidado con la cardinalidad: etiquetar por ruta con parámetros (/v1/cafes/caf_001) genera una serie temporal por café y hace estallar la memoria de Prometheus. Se etiqueta por plantilla de ruta y por cliente, que son conjuntos pequeños y acotados.

Qué campos no usa nadie. Una API REST devuelve la representación completa, así que no sabes qué lee el cliente… salvo que se lo preguntes. Dos técnicas baratas: (a) medir el uso del parámetro de proyección si lo tienes (?campos=), y (b) preguntar directamente en la encuesta anual a integradores. En Tienda Aroma descubrimos así que notasCata sólo lo consumían la SPA y CataBox, y que el campo _links.self de cada elemento de colección no lo usaba absolutamente nadie: los clientes construían las URLs por concatenación. Dato incómodo que se apuntó en la autocrítica de HATEOAS de 06-01.

Errores 4xx recurrentes por cliente. Es la mejor lista de tareas de documentación que existe:

Y el canal de soporte: una dirección [email protected] que llega a un humano, con el compromiso público de responder en 2 días laborables. Cada ticket se etiqueta como defecto, documentación o petición de funcionalidad; los de documentación se cierran editando el openapi.yaml, nunca respondiendo sólo por correo.

Mes 11. El equipo hace una lista de "cosas que arreglaríamos si empezáramos hoy" y se da cuenta de que ninguna se puede arreglar. Eso es deuda de contrato: decisiones publicadas que ya no son las mejores, pero que sostienen a consumidores reales.

Se acumula por tres motivos, y ninguno es negligencia:

• El dominio cambia. Cuando se diseñó tueste con tres valores no existía el tueste filtro en el catálogo.
• El estándar cambia o se conoce mejor. application/problem+json (RFC 9457) existía, pero se optó por un formato propio; hoy sería la opción obvia.
• Aciertas al 80 %. El envoltorio {"datos": [...], "total": n} funcionó bien, pero encarece cada respuesta y confunde a los clientes que esperan un array desnudo.

En 06-01 ya criticamos cuatro decisiones. Ahora tienen precio:

El artefacto que hace que esto no se olvide es el registro de deuda de contrato, versionado junto al código en docs/deuda-contrato.yaml. Es un documento vivo: se revisa cada trimestre y es la materia prima de la decisión sobre v2.

Fíjate en la nota de DC-007: parte de la deuda se puede pagar sin romper nada si se piensa en términos de negociación de contenido (02-05). No toda deuda exige una versión nueva.

Antes de plantearse una v2, hay que agotar lo que se puede hacer dentro de v1. La regla general la vimos en 02-07: añadir es seguro, quitar y cambiar el significado no lo es. El detalle importa mucho más de lo que parece.

* El asterisco del campo nuevo. "Añadir un campo no rompe nada" sólo es cierto si los clientes son tolerant readers: si ignoran lo que no conocen. Un cliente que valide la respuesta contra un esquema estricto con additionalProperties: false, o que use un lenguaje que falle al deserializar campos desconocidos, se rompe con un campo nuevo. Por eso la guía de integración de Tienda Aroma dice esto en la primera página:

El caso peligroso: endurecer una validación. En el mes 14 se descubrió que notasCata admitía textos de cualquier longitud y alguien había guardado 40 KB. La tentación es añadir .max(500) en el esquema Zod (03-02) y desplegar. Eso convierte peticiones antes válidas en 422 datos_invalidos: es un cambio rompedor aunque no toque ni un nombre de campo. El procedimiento correcto es en dos tiempos.

Si al cabo de seis semanas el contador sigue subiendo, no se despliega la fase 2: se llama al cliente. La fecha se mueve; el contrato no se rompe por sorpresa.

Una v2 no es un logro, es una factura: dos bases de código o dos capas de traducción, dos juegos de pruebas, dos documentaciones, dos versiones del openapi.yaml, y consumidores que tardarán meses en moverse. Criterios honestos:

Señales de que NO toca v2:

• El cambio se puede hacer añadiendo (apartado 7).
• Molesta al equipo pero no a los consumidores (notasCata por sí solo no justifica nada).
• Es un problema de documentación disfrazado de problema de diseño.
• Hay menos de tres deudas de impacto alto acumuladas.

Señales de que SÍ toca:

• Varias deudas de impacto alto que sólo se resuelven rompiendo, y que causan incidentes o soporte recurrente.
• El modelo de dominio ha cambiado de verdad (Tienda Aroma pasó a vender suscripciones, y un pedido recurrente no encaja en el recurso /pedidos actual).
• Cambios de seguridad no negociables.
• El coste de mantener los apaños supera el coste de migrar.

Mes 18. Tienda Aroma decide la v2 con cuatro deudas de impacto alto y un dominio nuevo (suscripciones). Se escribe un ADR en docs/decisiones/0031-lanzar-v2.md con la alternativa descartada (seguir parcheando v1 con problem+json negociado y un recurso /suscripciones colgado de v1) y por qué se rechaza.

Recordemos la política publicada: versionado sólo en la ruta, y v1 y v2 conviven al menos 6 meses. En la práctica, para una API con socios externos, seis meses es el mínimo legal y doce el mínimo razonable.

Es el documento que decide si la migración es de dos días o de dos meses para el consumidor. Nada de prosa: equivalencias literales.

Retomando 02-07, así responde v1 a partir del mes 1:

Con la etiqueta version del contador del apartado 5, la pregunta se responde sola:

Ese segundo resultado es el motivo por el que no se apaga una versión por calendario sin mirar las métricas: aparece siempre un consumidor olvidado. Y el tercero recuerda que en las apps móviles no controlas cuándo actualiza el usuario: la app antigua seguirá viva durante meses.

Un brownout es un apagado breve y anunciado de v1: durante la ventana, todas las peticiones reciben 410. Su función no es técnica, es psicológica: convierte una fecha lejana en un incidente real en el entorno del consumidor, que es lo único que mueve prioridades.

Y el apagado definitivo, ya sin Retry-After:

410 Gone y no 404: la diferencia comunica que el recurso existió y desapareció a propósito, y evita que un cliente crea que se ha equivocado de ruta.

Año 2. El endpoint GET /v1/cafes/{id}/maridajes, añadido en el mes 4 por petición de marketing, recibe 40 peticiones al mes de un único cliente. Su coste no es cero:

• Aparece en openapi.yaml, así que hay que documentarlo y revisarlo con Spectral.
• Tiene pruebas que se ejecutan en cada CI y que a veces fallan por datos de prueba.
• Tiene una tabla con su migración, que hay que arrastrar en cada cambio de esquema.
• Bloquea decisiones: cualquier refactor del recurso Cafe debe contemplarlo.
• Ocupa espacio mental en cada revisión de diseño.

La retirada de una funcionalidad concreta sigue el mismo protocolo que una versión, en pequeño: anuncio, Deprecation/Sunset sólo en esa ruta, contacto con el único consumidor, y 410. Duró tres meses. Lo que no se debe hacer nunca es borrarlo porque "casi nadie lo usa": ese "casi" es una empresa que depende de ello.

Trabajo recurrente que no produce funcionalidades y sin el cual la API se degrada sola.

Dependencias y CVE. Auditoría semanal automatizada en el ci.yml de 05-04:

La política acordada: vulnerabilidad crítica en dependencia explotable, parche en 48 h; alta, en 7 días; el resto, en la ventana mensual de mantenimiento.

Versión de Node. Node 20 entra en fin de soporte y hay que saltar a la siguiente LTS. Es un cambio invisible para el consumidor y peligroso para ti: se hace por canary (05-04), con el 5 % del tráfico durante 48 h, comparando p95 y tasa de error entre ambos grupos. Se apunta en el calendario antes de que el soporte expire, no después.

Rotación de secretos y claves de firma. Tres relojes distintos:

Revisión de SLO. Cada semestre. Si el SLO del 99,9 % nunca se ha rozado en un año, o está mal medido o es demasiado laxo. Si se incumple cada mes, o no es alcanzable con la arquitectura actual, o el presupuesto de error se está usando como excusa. En Tienda Aroma, el SLO de latencia de /cafes se endureció de 400 ms a 300 ms en el año 2 tras el trabajo de índices.

Revisión de seguridad. Repaso anual del OWASP API Top 10 (04-01) contra el estado real: autorización a nivel de objeto en cada endpoint nuevo, límites de consumo, exposición de datos. Se documenta como cualquier revisión de diseño.

El coste de infraestructura como señal de diseño. La factura de la API es una métrica de diseño disfrazada de métrica financiera. Si un endpoint cuesta desproporcionadamente, casi siempre hay una decisión de contrato detrás: GET /v1/pedidos sin paginación obligatoria devolviendo miles de elementos, ausencia de ETag en un recurso muy consultado, o un cliente haciendo polling donde debería haber un webhook. Antes de escalar la infraestructura, revisa el contrato: sale más barato.

En 04-02 definimos la propiedad de cada API y en 05-06 montamos el portal de desarrollador con su inventario. Su utilidad real aparece justo ahora: en la migración a v2 apareció un consumidor llamado integracion-erp que nadie recordaba haber autorizado. Existía, funcionaba y estaba en producción.

Una API zombi es una API (o una versión, o un endpoint) que sigue respondiendo, consume recursos y presenta superficie de ataque, pero no tiene dueño identificable. Se detectan cruzando tres fuentes: el inventario declarado, las métricas reales de tráfico y el registro de credenciales emitidas. Cualquier fila que aparezca en una fuente y falte en otra es una alarma.

Cada entrada del inventario debe responder, como mínimo: quién la mantiene, quién la consume, qué versión está vigente, qué fecha de retirada tiene si está deprecada, y dónde está su openapi.yaml. Sin dueño no se despliega: es la única forma de que el inventario no envejezca.

Año 3. Ya no hay un equipo, hay tres: catálogo, pedidos y suscripciones. Sin gobierno, en seis meses tienes tres APIs que parecen de tres empresas distintas: una con snake_case, otra con errores en texto plano, otra paginando con page/size.

El gobierno de Tienda Aroma se apoya en cuatro piezas, todas ya conocidas:

• La guía de estilo (02-01) como norma escrita, no como recomendación. Es la referencia que zanja discusiones en una revisión.
• La revisión de diseño: antes de escribir código, el equipo presenta el fragmento de openapi.yaml propuesto. Diez minutos con dos personas de otros equipos evitan meses de deuda. Se revisa el contrato, no la implementación.
• Puertas automáticas en CI (05-04/05-05): Spectral valida el estilo y oasdiff detecta cambios rompedores. Lo automático no se discute, y eso es precisamente su virtud.
• ADR en docs/decisiones/: cada decisión estructural con su contexto, alternativas y consecuencias. Sirve para que dentro de dos años nadie "arregle" algo que estaba así a propósito.

Y el flujo humano completo de un cambio de contrato:

• Depurar en caliente en lugar de mitigar. Cada minuto de diagnóstico durante un S1 se paga con presupuesto de error. Revierte, apaga la flag, y luego investiga.
• Post-mortems que terminan en "falta de atención". Si la acción no se puede cerrar con un enlace verificable, no es una acción. Y si el documento nombra a una persona como causa, la próxima vez nadie contará lo que pasó.
• Confundir "sin culpables" con "sin consecuencias". Las acciones tienen responsable y plazo, y se revisan en la retrospectiva del mes siguiente.
• Creer que añadir un campo nunca rompe. Sólo es cierto con clientes tolerant readers. Publica ese requisito en la guía de integración desde el día uno.
• Endurecer validaciones sin fase de aviso. Es el cambio rompedor que más se cuela porque no toca el esquema visible. Mide primero, rechaza después.
• Etiquetar métricas por ruta concreta o por id. La cardinalidad estalla y te quedas sin observabilidad justo cuando la necesitas. Plantillas de ruta y conjuntos cerrados.
• Apagar v1 por calendario sin mirar métricas por versión. Siempre aparece un consumidor olvidado. Las métricas mandan sobre el calendario; el Sunset anunciado no se adelanta, pero sí se puede retrasar.
• Lanzar v2 por incomodidad interna. Si el dolor lo sufre sólo tu equipo, resuélvelo por dentro. Una versión nueva es una factura que pagan todos tus consumidores.
• Tratar los 4xx como culpa del cliente. Son tu lista de tareas de documentación ordenada por impacto.
• Consejo final: publica el calendario de deprecación en un sitio estable y respétalo aunque duela. Un Sunset que se adelanta destruye más confianza que un incidente de 34 minutos.

Para cada cambio propuesto sobre v1 de Tienda Aroma, indica si es retrocompatible, si es rompedor, y cuál sería la estrategia correcta:

1. Añadir el campo origenCertificado (booleano) a la representación de Cafe.
2. Añadir el valor filtro al enumerado tueste en las respuestas.
3. Cambiar el limite por defecto de GET /v1/cafes de 20 a 50.
4. Empezar a rechazar precioMin negativo con 422 datos_invalidos.
5. Añadir el filtro opcional ?certificado=true.

Una API interna de facturación acumula estas deudas: (a) el campo total está en euros como número decimal y provoca errores de redondeo; (b) GET /facturas no pagina y devuelve hasta 4.000 elementos; (c) el nombre factura_id usa snake_case mientras el resto de la API usa camelCase. Sólo hay dos consumidores, ambos internos. ¿Lanzarías una v2? Justifica con criterios, no con gustos.

Un despliegue del viernes por la tarde introdujo un fallo en la renovación de tokens: durante 18 minutos, todas las peticiones de Aroma Móvil recibieron 401 no_autenticado. Se detectó porque un usuario escribió en redes sociales; nadie del equipo vio ninguna alerta. Escribe cinco acciones para el post-mortem, cada una con tipo (correctiva, detección, preventiva, organizativa, comunicación) y un criterio de cierre verificable.

Ejercicio 1

Ejercicio 2

No, todavía no. Análisis por deuda:

• (a) total decimal en euros. Es real y grave (redondeo en dinero), pero se resuelve añadiendo: publicar totalCentimos como campo nuevo, documentarlo como preferente, deprecar total en la documentación y medir su uso. No requiere versión.
• (b) GET /facturas sin paginación. Se puede paginar de forma retrocompatible: aceptar limite/desplazamiento, y mientras no se envíen, devolver el comportamiento actual. Con dos consumidores internos, se puede negociar además un límite máximo con aviso previo. No requiere versión.
• (c) factura_id en snake_case. Es incomodidad estética. Solución: emitir también facturaId (ambos campos conviven), documentar el nuevo, y eliminar el viejo cuando las métricas de uso lo permitan o llegue una v2 motivada por otra cosa.

Además, con dos consumidores internos el coste de coordinación es bajísimo comparado con el de mantener dos versiones. Criterio aplicable: ninguna de las tres deudas obliga a romper, luego no hay v2. Lo que sí procede es abrir tres entradas en el registro de deuda de contrato con candidata_v2: true y revisarlas cada trimestre.

Ejercicio 3

Observa que la acción 2 es la más valiosa: el fallo duró 18 minutos, pero el problema real es que la detección llegó desde fuera. Un incidente que descubre un usuario en redes sociales es, ante todo, un fallo de observabilidad.

Diseñar una API es un ejercicio acotado; mantenerla es un compromiso indefinido. En esta lección hemos recorrido tres años de la API de Tienda Aroma y hemos visto que casi todo el trabajo posterior al lanzamiento consiste en proteger a quien ya confía en ti: vigilar las señales adecuadas desde el primer día, mitigar antes de diagnosticar cuando algo se rompe, escribir post-mortems que arreglen el sistema en vez de buscar responsables, escuchar lo que los 4xx y la analítica de uso te están diciendo, anotar la deuda de contrato en lugar de fingir que no existe, agotar todo lo que se puede añadir sin romper, y —sólo cuando ya no queda alternativa— planificar una v2 con su calendario, sus cabeceras Deprecation y Sunset, sus brownouts y su 410 final. A eso se suma el mantenimiento que nadie aplaude: CVE, versiones de Node, rotación de claves, revisión de SLO, inventario sin zombis y un gobierno con Spectral, oasdiff y ADR que mantenga la coherencia cuando ya no hay un solo equipo.

La conclusión de fondo es sencilla y exigente a la vez: una API es un compromiso a largo plazo con quien la consume. Cada campo publicado es una promesa, cada Sunset anunciado es un contrato, y la confianza que construyes durante tres años puede perderse con un cambio "inocuo" desplegado un viernes por la tarde. La calidad de una API no se mide el día del lanzamiento, sino en la facilidad con la que un integrador sigue trabajando con ella cuando ya nadie del equipo original queda en la empresa.

Con esto cerramos el recorrido de casos prácticos y análisis. Te toca a ti: en 06-04, Proyecto final: Diseñar y desarrollar tu propia API RESTful, aplicarás por fases todo lo aprendido —diseño del contrato, implementación, seguridad, documentación y despliegue— sobre un dominio propio, con una rúbrica clara para autoevaluarte. Todo lo que hemos hecho hasta ahora estaba preparando ese encargo.