A 06-02 vam comparar el disseny de la Botiga Aroma amb el de CafeSocial i vam tancar amb una tesi incòmoda: no existeix un disseny REST universal. Ara arriba l'últim assumpte, el que separa una API ben dissenyada d'una API que continua viva al cap de tres anys: què passa després de publicar-la. Perquè el dia del llançament l'API és teva; a partir de la primera integració és dels teus consumidors, i cada camp que retornes es converteix en una promesa. Aquesta lliçó recorre els tres primers anys de l'API de la Botiga Aroma com una línia temporal amb fites concretes: el primer incident, el post-mortem de la caiguda de Nadal, el deute de contracte que es va acumulant, la migració a v2 amb el seu calendari de dotze mesos i la feina silenciosa de manteniment que ningú no veu però que sosté tota la resta.

1. La línia temporal d'una API en producció
2. El primer dia: què es vigila i què és normal
3. Gestió d'incidents: gravetats, mitigació i comunicació
4. El post-mortem sense culpables (document complet)
5. Escoltar els consumidors
6. El deute de contracte
7. Afegir sense trencar: catàleg de canvis segurs
8. Quan toca una v2 i com es migra en 12 mesos
9. Retirar funcionalitats i el cost del que gairebé ningú no fa servir
10. Manteniment continu: dependències, secrets, SLO i cost
11. Inventari d'APIs i APIs zombis
12. Govern amb diversos equips
13. Errors comuns, exercicis i conclusió

Convé veure el cicle complet abans d'entrar en cada fita. Aquests són els moments que van marcar els tres primers anys de https://api.botigaaroma.example/v1.

Cap d'aquestes fites no és un projecte nou: totes són manteniment. I el manteniment consumeix, en una API amb diversos consumidors externs, bastant més esforç acumulat que la construcció inicial.

El mes 0 l'API es publica amb dos consumidors propis: la SPA https://botigaaroma.example i el tauler intern. Tot l'instrumental que vam muntar a 04-07 (pino per als logs estructurats, prom-client per a les mètriques, traces amb OpenTelemetry, /salut/viu i /salut/llest) deixa de ser un exercici i passa a ser l'únic lloc on es pot mirar.

Els quatre senyals que es vigilen des del minut u són els clàssics d'un servei de petició-resposta:

I hi ha un cinquè senyal que gairebé ningú no mira el primer dia i que resulta ser el més informatiu: la distribució dels 4xx.

Sortida real del segon dia:

Què és normal i què no. Els 401 són normals: la SPA reintenta amb el token caducat i el renova. Els 404 sobre /cafes/{id} també: hi ha enllaços antics indexats. El que no és normal són 412 parametre_invalid a GET /v1/cafes: això no és un client maldestre, és un contracte mal explicat. En inspeccionar els detalls de l'error apareix el patró: els clients envien ?torrefaccio=Mitja amb majúscula inicial, i el nostre enumerat només accepta clar|mitja|fosc. La documentació ho deia; el missatge d'error, no. Es va corregir el missatge —no la validació— i els 400 van baixar a 20 al dia.

Regla del primer dia: un error 4xx repetit no acusa el client, descriu un defecte de disseny o de documentació de la teva API.

El primer incident (mes 2). Amb el llançament d'Aroma Mòbil apareixen els primers 429. L'app fa polling de la cistella cada 5 segons i el rate limiting de 04-04 comença a retornar limit_peticions amb Retry-After. El diagnòstic va trigar vint minuts perquè les capçaleres Aroma-RateLimit-Restants no s'estaven registrant als logs. La solució no va ser apujar el límit: va ser afegir ETag a la cistella (ja el teníem a /cafes, vegeu 04-05) perquè el polling respongués 304 Not Modified a un cost gairebé nul, i publicar a la guia d'integració que l'interval recomanat era de 30 segons.

A 04-07 vam fixar un SLO de disponibilitat del 99,9 % mensual per a les rutes de lectura. Aquest 0,1 % són 43 minuts de pressupost d'error al mes. El pressupost és el que converteix una discussió d'opinions ("això és greu?") en una decisió aritmètica: si en tres dies s'ha consumit el 60 % del pressupost mensual, es congelen els desplegaments de funcionalitat i l'equip es dedica a la fiabilitat fins que la taxa es recuperi.

Les alertes no es disparen sobre llindars instantanis, sinó sobre velocitat de consum del pressupost (burn rate): consumir el pressupost 14 vegades més ràpid del que és sostenible durant 5 minuts és un avís immediat; 6 vegades més ràpid durant una hora, un avís normal.

És la regla més difícil d'interioritzar per a un equip tècnic, perquè la curiositat empeny cap al perquè. Durant un incident, l'ordre correcte és:

1. Restaurar el servei amb el que sigui: revertir l'últim desplegament, apagar la feature flag (05-04), tornar el trànsit al color anterior al blue-green, degradar una funcionalitat.
2. Preservar evidències: capturar traces, Aroma-Traca-Id de peticions fallides, sortida d'EXPLAIN, mètriques de l'interval.
3. Després, entendre la causa arrel amb calma.

Un desplegament revertit en 4 minuts costa un post-mortem; un desplegament depurat en calent durant 40 minuts costa el pressupost d'error del trimestre.

Amb consumidors externs —RàpidEnviaments i CataBox—, callar és pitjor que equivocar-se. El patró que vam adoptar: una entrada a la pàgina d'estat en menys de 15 minuts encara que no se'n sàpiga res ("estem investigant errors en la creació de comandes"), actualitzacions cada 30 minuts, i una nota final amb l'enllaç al post-mortem quan estigui publicat. Res de detalls interns d'infraestructura; sí l'impacte observable i el consell de reintent.

Mes 7, 18 de desembre. La campanya de Nadal multiplica el trànsit per sis. Dues setmanes abans s'havia afegit el filtre ?origen= a GET /v1/cafes —un canvi retrocompatible de manual, tres línies de codi— però sense índex a la columna corresponent. Amb el catàleg crescut i el trànsit de campanya, la base de dades se satura i l'API queda inaccessible 34 minuts.

Aquest és el document tal com va quedar a docs/incidents/. Fixa't en el que no conté: cap nom associat a la causa.

La verificació de l'acció 1, perquè quedi clar què es comprova:

Sense culpables no vol dir sense responsables. Les accions tenen amo i termini; la causa no té amo. La persona que va afegir el filtre sense índex va fer el que el sistema li permetia fer: no hi havia llista de revisió, ni prova de càrrega, ni alerta. El sistema va fallar, i el sistema és el que s'arregla.

A partir del mes 9, la pregunta deixa de ser "funciona?" i passa a ser "què hi estan fent realment?". Tres fonts:

Analítica d'ús per endpoint i per client. Cada token JWT porta un client_id (04-02). S'etiqueta la mètrica de peticions amb aquest identificador, però amb compte amb la cardinalitat: etiquetar per ruta amb paràmetres (/v1/cafes/caf_001) genera una sèrie temporal per cafè i fa esclatar la memòria de Prometheus. S'etiqueta per plantilla de ruta i per client, que són conjunts petits i acotats.

Quins camps no fa servir ningú. Una API REST retorna la representació completa, així que no saps què llegeix el client… tret que li ho preguntis. Dues tècniques barates: (a) mesurar l'ús del paràmetre de projecció si el tens (?camps=), i (b) preguntar-ho directament a l'enquesta anual als integradors. A la Botiga Aroma vam descobrir així que notesTast només el consumien la SPA i CataBox, i que el camp _links.self de cada element de col·lecció no el feia servir absolutament ningú: els clients construïen les URL per concatenació. Dada incòmoda que es va apuntar a l'autocrítica d'HATEOAS de 06-01.

Errors 4xx recurrents per client. És la millor llista de tasques de documentació que existeix:

I el canal de suport: una adreça [email protected] que arriba a un humà, amb el compromís públic de respondre en 2 dies laborables. Cada tiquet s'etiqueta com a defecte, documentació o petició de funcionalitat; els de documentació es tanquen editant l'openapi.yaml, mai responent només per correu.

Mes 11. L'equip fa una llista de "coses que arreglaríem si comencéssim avui" i s'adona que cap no es pot arreglar. Això és deute de contracte: decisions publicades que ja no són les millors, però que sostenen consumidors reals.

S'acumula per tres motius, i cap no és negligència:

• El domini canvia. Quan es va dissenyar torrefaccio amb tres valors no existia la torrefacció filtre al catàleg.
• L'estàndard canvia o es coneix millor. application/problem+json (RFC 9457) existia, però es va optar per un format propi; avui seria l'opció òbvia.
• Encertes al 80 %. L'embolcall {"dades": [...], "total": n} va funcionar bé, però encareix cada resposta i confon els clients que esperen un array pelat.

A 06-01 ja vam criticar quatre decisions. Ara tenen preu:

L'artefacte que fa que això no s'oblidi és el registre de deute de contracte, versionat juntament amb el codi a docs/deute-contracte.yaml. És un document viu: es revisa cada trimestre i és la matèria primera de la decisió sobre la v2.

Fixa't en la nota de DC-007: part del deute es pot pagar sense trencar res si es pensa en termes de negociació de contingut (02-05). No tot deute exigeix una versió nova.

Abans de plantejar-se una v2, cal esgotar el que es pot fer dins de v1. La regla general la vam veure a 02-07: afegir és segur, treure i canviar el significat no ho és. El detall importa molt més del que sembla.

* L'asterisc del camp nou. "Afegir un camp no trenca res" només és cert si els clients són tolerant readers: si ignoren el que no coneixen. Un client que validi la resposta contra un esquema estricte amb additionalProperties: false, o que faci servir un llenguatge que falli en deserialitzar camps desconeguts, es trenca amb un camp nou. Per això la guia d'integració de la Botiga Aroma diu això a la primera pàgina:

El cas perillós: endurir una validació. El mes 14 es va descobrir que notesTast admetia textos de qualsevol longitud i algú hi havia desat 40 KB. La temptació és afegir .max(500) a l'esquema Zod (03-02) i desplegar. Això converteix peticions abans vàlides en 422 dades_invalides: és un canvi trencador encara que no toqui cap nom de camp. El procediment correcte és en dos temps.

Si al cap de sis setmanes el comptador continua pujant, no es desplega la fase 2: es truca al client. La data es mou; el contracte no es trenca per sorpresa.

Una v2 no és una fita assolida, és una factura: dues bases de codi o dues capes de traducció, dos jocs de proves, dues documentacions, dues versions de l'openapi.yaml, i consumidors que trigaran mesos a moure's. Criteris honestos:

Senyals que NO toca v2:

• El canvi es pot fer afegint (apartat 7).
• Molesta l'equip però no els consumidors (notesTast per si sol no justifica res).
• És un problema de documentació disfressat de problema de disseny.
• Hi ha menys de tres deutes d'impacte alt acumulats.

Senyals que SÍ que toca:

• Diversos deutes d'impacte alt que només es resolen trencant, i que causen incidents o suport recurrent.
• El model de domini ha canviat de debò (la Botiga Aroma va passar a vendre subscripcions, i una comanda recurrent no encaixa en el recurs /comandes actual).
• Canvis de seguretat no negociables.
• El cost de mantenir els pedaços supera el cost de migrar.

Mes 18. La Botiga Aroma decideix la v2 amb quatre deutes d'impacte alt i un domini nou (subscripcions). S'escriu un ADR a docs/decisions/0031-llancar-v2.md amb l'alternativa descartada (continuar apedaçant la v1 amb problem+json negociat i un recurs /subscripcions penjat de la v1) i per què es rebutja.

Recordem la política publicada: versionat només a la ruta, i v1 i v2 conviuen com a mínim 6 mesos. A la pràctica, per a una API amb socis externs, sis mesos és el mínim legal i dotze el mínim raonable.

És el document que decideix si la migració és de dos dies o de dos mesos per al consumidor. Res de prosa: equivalències literals.

Reprenent 02-07, així respon v1 a partir del mes 1:

Amb l'etiqueta versio del comptador de l'apartat 5, la pregunta es respon sola:

Aquest segon resultat és el motiu pel qual no s'apaga una versió per calendari sense mirar les mètriques: sempre apareix un consumidor oblidat. I el tercer recorda que a les apps mòbils no controles quan actualitza l'usuari: l'app antiga continuarà viva durant mesos.

Un brownout és una apagada breu programada i anunciada de v1: durant la finestra, totes les peticions reben 410. La seva funció no és tècnica, és psicològica: converteix una data llunyana en un incident real a l'entorn del consumidor, que és l'única cosa que mou prioritats.

I l'apagada definitiva, ja sense Retry-After:

410 Gone i no 404: la diferència comunica que el recurs va existir i va desaparèixer a propòsit, i evita que un client cregui que s'ha equivocat de ruta.

Any 2. L'endpoint GET /v1/cafes/{id}/maridatges, afegit el mes 4 per petició de màrqueting, rep 40 peticions al mes d'un únic client. El seu cost no és zero:

• Apareix a openapi.yaml, així que cal documentar-lo i revisar-lo amb Spectral.
• Té proves que s'executen a cada CI i que de vegades fallen per dades de prova.
• Té una taula amb la seva migració, que cal arrossegar a cada canvi d'esquema.
• Bloqueja decisions: qualsevol refactorització del recurs Cafe l'ha de contemplar.
• Ocupa espai mental a cada revisió de disseny.

La retirada d'una funcionalitat concreta segueix el mateix protocol que una versió, en petit: anunci, Deprecation/Sunset només en aquella ruta, contacte amb l'únic consumidor, i 410. Va durar tres mesos. El que no s'ha de fer mai és esborrar-lo perquè "gairebé ningú no el fa servir": aquest "gairebé" és una empresa que en depèn.

Feina recurrent que no produeix funcionalitats i sense la qual l'API es degrada sola.

Dependències i CVE. Auditoria setmanal automatitzada al ci.yml de 05-04:

La política acordada: vulnerabilitat crítica en una dependència explotable, pedaç en 48 h; alta, en 7 dies; la resta, a la finestra mensual de manteniment.

Versió de Node. Node 20 entra en fi de suport i cal saltar a la LTS següent. És un canvi invisible per al consumidor i perillós per a tu: es fa per canary (05-04), amb el 5 % del trànsit durant 48 h, comparant p95 i taxa d'error entre tots dos grups. S'apunta al calendari abans que el suport expiri, no després.

Rotació de secrets i claus de signatura. Tres rellotges diferents:

Revisió dels SLO. Cada semestre. Si l'SLO del 99,9 % no s'ha fregat mai en un any, o està mal mesurat o és massa laxe. Si s'incompleix cada mes, o no és assolible amb l'arquitectura actual, o el pressupost d'error s'està fent servir com a excusa. A la Botiga Aroma, l'SLO de latència de /cafes es va endurir de 400 ms a 300 ms l'any 2 després de la feina d'índexs.

Revisió de seguretat. Repàs anual de l'OWASP API Top 10 (04-01) contra l'estat real: autorització a nivell d'objecte a cada endpoint nou, límits de consum, exposició de dades. Es documenta com qualsevol revisió de disseny.

El cost d'infraestructura com a senyal de disseny. La factura de l'API és una mètrica de disseny disfressada de mètrica financera. Si un endpoint costa desproporcionadament, gairebé sempre hi ha una decisió de contracte al darrere: GET /v1/comandes sense paginació obligatòria retornant milers d'elements, absència d'ETag en un recurs molt consultat, o un client fent polling on hi hauria d'haver un webhook. Abans d'escalar la infraestructura, revisa el contracte: surt més barat.

A 04-02 vam definir la propietat de cada API i a 05-06 vam muntar el portal de desenvolupador amb el seu inventari. La seva utilitat real apareix just ara: a la migració a v2 va aparèixer un consumidor anomenat integracio-erp que ningú no recordava haver autoritzat. Existia, funcionava i era en producció.

Una API zombi és una API (o una versió, o un endpoint) que continua responent, consumeix recursos i presenta superfície d'atac, però no té amo identificable. Es detecten creuant tres fonts: l'inventari declarat, les mètriques reals de trànsit i el registre de credencials emeses. Qualsevol fila que aparegui en una font i falti en una altra és una alarma.

Cada entrada de l'inventari ha de respondre, com a mínim: qui la manté, qui la consumeix, quina versió està vigent, quina data de retirada té si està deprecada, i on és el seu openapi.yaml. Sense amo no es desplega: és l'única manera que l'inventari no envelleixi.

Any 3. Ja no hi ha un equip, n'hi ha tres: catàleg, comandes i subscripcions. Sense govern, en sis mesos tens tres APIs que semblen de tres empreses diferents: una amb snake_case, una altra amb errors en text pla, una altra paginant amb page/size.

El govern de la Botiga Aroma es recolza en quatre peces, totes ja conegudes:

• La guia d'estil (02-01) com a norma escrita, no com a recomanació. És la referència que tanca discussions en una revisió.
• La revisió de disseny: abans d'escriure codi, l'equip presenta el fragment d'openapi.yaml proposat. Deu minuts amb dues persones d'altres equips eviten mesos de deute. Es revisa el contracte, no la implementació.
• Portes automàtiques a CI (05-04/05-05): Spectral valida l'estil i oasdiff detecta canvis trencadors. El que és automàtic no es discuteix, i això és precisament la seva virtut.
• ADR a docs/decisions/: cada decisió estructural amb el seu context, alternatives i conseqüències. Serveix perquè d'aquí a dos anys ningú no "arregli" alguna cosa que era així a propòsit.

I el flux humà complet d'un canvi de contracte:

• Depurar en calent en lloc de mitigar. Cada minut de diagnòstic durant un S1 es paga amb pressupost d'error. Reverteix, apaga la flag, i després investiga.
• Post-mortems que acaben en "manca d'atenció". Si l'acció no es pot tancar amb un enllaç verificable, no és una acció. I si el document anomena una persona com a causa, la propera vegada ningú no explicarà què va passar.
• Confondre "sense culpables" amb "sense conseqüències". Les accions tenen responsable i termini, i es revisen a la retrospectiva del mes següent.
• Creure que afegir un camp no trenca mai. Només és cert amb clients tolerant readers. Publica aquest requisit a la guia d'integració des del primer dia.
• Endurir validacions sense fase d'avís. És el canvi trencador que més s'escola perquè no toca l'esquema visible. Mesura primer, rebutja després.
• Etiquetar mètriques per ruta concreta o per id. La cardinalitat esclata i et quedes sense observabilitat justament quan la necessites. Plantilles de ruta i conjunts tancats.
• Apagar v1 per calendari sense mirar les mètriques per versió. Sempre apareix un consumidor oblidat. Les mètriques manen sobre el calendari; el Sunset anunciat no s'avança, però sí que es pot endarrerir.
• Llançar una v2 per incomoditat interna. Si el dolor el pateix només el teu equip, resol-lo per dins. Una versió nova és una factura que paguen tots els teus consumidors.
• Tractar els 4xx com a culpa del client. Són la teva llista de tasques de documentació ordenada per impacte.
• Consell final: publica el calendari de deprecació en un lloc estable i respecta'l encara que faci mal. Un Sunset que s'avança destrueix més confiança que un incident de 34 minuts.

Per a cada canvi proposat sobre la v1 de la Botiga Aroma, indica si és retrocompatible, si és trencador, i quina seria l'estratègia correcta:

1. Afegir el camp origenCertificat (booleà) a la representació de Cafe.
2. Afegir el valor filtre a l'enumerat torrefaccio a les respostes.
3. Canviar el limit per defecte de GET /v1/cafes de 20 a 50.
4. Començar a rebutjar preuMin negatiu amb 422 dades_invalides.
5. Afegir el filtre opcional ?certificat=true.

Una API interna de facturació acumula aquests deutes: (a) el camp total és en euros com a nombre decimal i provoca errors d'arrodoniment; (b) GET /factures no pagina i retorna fins a 4.000 elements; (c) el nom factura_id fa servir snake_case mentre la resta de l'API fa servir camelCase. Només hi ha dos consumidors, tots dos interns. Llançaries una v2? Justifica-ho amb criteris, no amb gustos.

Un desplegament del divendres a la tarda va introduir una fallada en la renovació de tokens: durant 18 minuts, totes les peticions d'Aroma Mòbil van rebre 401 no_autenticat. Es va detectar perquè un usuari ho va escriure a les xarxes socials; ningú de l'equip no va veure cap alerta. Escriu cinc accions per al post-mortem, cadascuna amb tipus (correctiva, detecció, preventiva, organitzativa, comunicació) i un criteri de tancament verificable.

Exercici 1

Exercici 2

No, encara no. Anàlisi per deute:

• (a) total decimal en euros. És real i greu (arrodoniment en diners), però es resol afegint: publicar totalCentims com a camp nou, documentar-lo com a preferent, deprecar total a la documentació i mesurar-ne l'ús. No requereix versió.
• (b) GET /factures sense paginació. Es pot paginar de manera retrocompatible: acceptar limit/desplacament, i mentre no s'enviïn, retornar el comportament actual. Amb dos consumidors interns, a més es pot negociar un límit màxim amb avís previ. No requereix versió.
• (c) factura_id en snake_case. És incomoditat estètica. Solució: emetre també facturaId (tots dos camps conviuen), documentar el nou, i eliminar el vell quan les mètriques d'ús ho permetin o arribi una v2 motivada per una altra cosa.

A més, amb dos consumidors interns el cost de coordinació és baixíssim comparat amb el de mantenir dues versions. Criteri aplicable: cap dels tres deutes no obliga a trencar, per tant no hi ha v2. El que sí que escau és obrir tres entrades al registre de deute de contracte amb candidata_v2: true i revisar-les cada trimestre.

Exercici 3

Observa que l'acció 2 és la més valuosa: la fallada va durar 18 minuts, però el problema real és que la detecció va arribar des de fora. Un incident que descobreix un usuari a les xarxes socials és, abans de res, una fallada d'observabilitat.

Dissenyar una API és un exercici acotat; mantenir-la és un compromís indefinit. En aquesta lliçó hem recorregut tres anys de l'API de la Botiga Aroma i hem vist que gairebé tota la feina posterior al llançament consisteix a protegir qui ja confia en tu: vigilar els senyals adequats des del primer dia, mitigar abans de diagnosticar quan alguna cosa es trenca, escriure post-mortems que arreglin el sistema en lloc de buscar responsables, escoltar el que els 4xx i l'analítica d'ús t'estan dient, anotar el deute de contracte en lloc de fingir que no existeix, esgotar tot el que es pot afegir sense trencar, i —només quan ja no queda alternativa— planificar una v2 amb el seu calendari, les seves capçaleres Deprecation i Sunset, els seus brownouts i el seu 410 final. A això s'hi suma el manteniment que ningú no aplaudeix: CVE, versions de Node, rotació de claus, revisió dels SLO, inventari sense zombis i un govern amb Spectral, oasdiff i ADR que mantingui la coherència quan ja no hi ha un sol equip.

La conclusió de fons és senzilla i exigent alhora: una API és un compromís a llarg termini amb qui la consumeix. Cada camp publicat és una promesa, cada Sunset anunciat és un contracte, i la confiança que construeixes durant tres anys es pot perdre amb un canvi "innocu" desplegat un divendres a la tarda. La qualitat d'una API no es mesura el dia del llançament, sinó en la facilitat amb què un integrador continua treballant-hi quan ja no queda ningú de l'equip original a l'empresa.

Amb això tanquem el recorregut de casos pràctics i anàlisi. Et toca a tu: a 06-04, Projecte final: Dissenyar i desenvolupar la teva pròpia API RESTful, aplicaràs per fases tot el que has après —disseny del contracte, implementació, seguretat, documentació i desplegament— sobre un domini propi, amb una rúbrica clara per autoavaluar-te. Tot el que hem fet fins ara estava preparant aquest encàrrec.