Durant cinc mòduls hem anat construint l'API de la Botiga Aroma per parts: primer els conceptes, després el disseny, després el codi, la seguretat, l'operació i les eines. Cada lliçó resolia un problema i en deixava un altre d'obert. Aquesta lliçó fa una cosa diferent: mira el resultat complet i pregunta per què és així.

No és un resum. Un resum repetiria el que ja saps; aquí el que interessa és la justificació de conjunt, que és el que mai no apareix quan aprens peça a peça. Per què la cistella va acabar sent un recurs i el procés de compra no. Per què les comandes es paginen per cursor i els cafès per desplaçament. Per què els diners viatgen en euros però es desen en cèntims. I, sobretot, què es va descartar a cada bifurcació i quin preu es va pagar per triar.

Pensa en aquesta lliçó com la memòria tècnica que lliuraries a un equip que hereta el projecte: context, decisions amb la seva alternativa descartada, fluxos complets, els casos difícils que gairebé ningú no documenta, l'arquitectura desplegada, els objectius de nivell de servei i una autocrítica honesta del que no va sortir bé. Al final tindràs una llista de verificació que pots aplicar a qualsevol API que dissenyis.

1. El negoci i les seves restriccions
2. Els consumidors: cinc clients, cinc necessitats diferents
3. Casos d'ús crítics i requisits no funcionals
4. Del model de domini als recursos
5. El mapa complet d'URIs
6. Les decisions de disseny i les seves alternatives descartades
7. El flux complet d'una compra
8. Casos difícils i com es van resoldre
9. L'arquitectura desplegada
10. Mètriques i SLO del servei
11. El que faríem diferent
12. Llista de verificació final del projecte

La Botiga Aroma ven cafè d'especialitat. No és un supermercat: el catàleg té entre 40 i 120 referències vives, amb origen, torrefacció, notes de tast i lots que s'esgoten. El marge és alt, el volum és moderat i la fidelitat del client ho és tot: un comprador habitual demana cada tres o quatre setmanes durant anys.

Aquestes tres característiques del negoci condicionen l'API molt més del que sembla:

Cap d'aquestes decisions no surt d'un llibre d'estil. Surten del negoci. Aquest és el primer missatge de la lliçó: el mateix conjunt de regles REST produeix APIs diferents segons el domini, i a 06-02 ho veurem de manera molt més brutal.

A 01-01 vam dir que una API es dissenya per als seus consumidors, no per a la seva base de dades. La Botiga Aroma en té cinc, i cadascun estira el disseny en una direcció.

El detall important: els cinc consumeixen la mateixa API. No hi ha una API per a mòbil i una altra per a web. Va ser una decisió conscient, amb el seu cost: la SPA rep alguns camps que no fa servir, i el mòbil ha de demanar camps=id,nom,preuEuros per aprimar la resposta. L'alternativa —un backend for frontend per client— hauria donat respostes perfectes per a cadascun a canvi de multiplicar per tres el codi, les proves i el contracte. Amb cinc consumidors i un equip petit, no compensava. Amb vint consumidors i tres equips, la resposta hauria estat una altra.

Quatre casos d'ús concentren el 95 % del trànsit i tot el risc:

1. Cercar un cafè — GET /cafes amb filtres. És el 70 % de les peticions. Ha de ser rapidíssim i és totalment cacheable.
2. Comprar — cistella, comanda, pagament. És el 5 % de les peticions i el 100 % dels ingressos. Ha de ser correcte encara que sigui lent.
3. Seguir l'enviament — GET /comandes/{id} i /enviament. Genera sondeig repetit: molta memòria cau condicional i 304.
4. Moderar ressenyes — tauler intern. Volum baix, autorització estricta.

I els requisits no funcionals que vam acordar amb negoci:

Fixa't en l'asimetria deliberada: la lectura s'optimitza per a la velocitat i l'escriptura per a la correcció. Un catàleg que triga 400 ms molesta; una comanda cobrada dues vegades és una trucada al banc, una devolució i un client perdut.

A 02-02 vam veure el mètode: escriu com descriu el negoci la seva feina, subratlla els substantius i pregunta't quins tenen identitat pròpia, estat i cicle de vida. Aplicat a la Botiga Aroma:

Aquesta és la distinció que més costa i la que millor separa qui ha entès REST de qui tradueix funcions a URL.

La cistella és un recurs perquè compleix les tres proves: té identitat (cis_77), té estat que persisteix entre peticions (les línies que hi has afegit hi continuen sent demà) i respon amb sentit als mètodes HTTP. GET /cistelles/cis_77 retorna alguna cosa. DELETE /cistelles/cis_77 significa buidar-la. La pots enllaçar. La pots posar a la memòria cau (malament, perquè canvia, però el verb té sentit).

El procés de compra no és un recurs perquè és un procés: la transició d'una cistella a una comanda. No té estat propi per consultar. Un GET /compra no significa res. I sobretot: el resultat del procés sí que és un recurs, i ja té nom. El procés s'expressa creant aquest recurs:

L'alternativa hauria estat POST /compra, que funciona però no diu què s'ha creat, no pot retornar un Location coherent i no es deixa versionar ni enllaçar. La regla que en traiem: si un procés produeix alguna cosa amb identitat, exposa el que produeix, no el procés. I si un procés no produeix res de nou però canvia l'estat d'alguna cosa existent —pagar, enviar, anul·lar—, exposa aquesta transició com a subrecurs amb POST, que és exactament el que vam fer amb /comandes/{id}/pagament.

Aquest és el contracte complet de la v1, tal com va quedar:

Tres regularitats que sostenen tot el mapa i que un consumidor nou aprèn en cinc minuts:

• Plural sempre, sense excepcions. /cafes, no /cafe ni /coffeeList.
• Sense verbs a la ruta; el verb és el mètode HTTP. Les úniques "accions" són substantius de transició (/pagament, /anullacio).
• Màxim dos nivells d'imbricació, i el subrecurs sempre pertany de debò al pare.

Aquesta és la taula que més valor té en una memòria tècnica. Cada fila és una bifurcació real del projecte.

Aquí és on el disseny es posa a prova. Seguim la Marta Garcia (cli_842) des que busca cafè fins que descarrega la factura. Totes les peticions són reals segons el contracte de la v1.

Sense autenticació: el catàleg és públic. Amb ETag, perquè la visita següent rebi un 304 de 150 bytes (04-06). Amb Vary: Origin perquè la resposta porta capçaleres CORS i una memòria cau compartida no les ha de barrejar (04-05).

PUT i no POST. Aquesta és una de les decisions més útils de tot el contracte i val la pena explicar-la. Amb POST /cistelles/cis_77/linies, si l'usuari prem dues vegades "afegir" acaba amb dues línies del mateix cafè, o amb una lògica de fusió amagada al servidor. Amb PUT sobre la URI de la línia, l'operació és idempotent (02-03): "la quantitat de caf_001 en aquesta cistella és 2". Prémer deu vegades deixa el mateix resultat. La interfície de la cistella, amb el seu selector de quantitat, hi encaixa de manera natural: cada canvi del selector és un PUT.

I el subrecurs té URI pròpia, així que treure un cafè és DELETE /v1/cistelles/cis_77/linies/caf_001, sense cos i sense ambigüitat.

Aquí no es reserva estoc. És deliberat: reservar a la cistella obliga a fer caducar reserves, complica l'inventari i genera falsos "exhaurit" en campanya. L'estoc es comprova i es descompta en crear la comanda, dins d'una transacció.

A dins, tot passa dins d'una transacció (03-05): es llegeixen les línies de la cistella, es bloquegen i es comproven els estocs, es congela el preu unitari a cada línia, es calcula el total en cèntims, s'insereix la comanda, es descompta l'estoc i es buida la cistella. Si alguna cosa falla, no en queda cap rastre.

I a _links apareix la hipermèdia selectiva de la decisió 5: com que la comanda està pendent_pagament, el client veu pagament i anullacio. No veurà enviament ni devolucio, perquè encara no són possibles. La SPA no necessita conèixer la màquina d'estats: en té prou de pintar els enllaços que rep.

Tres mecanismes actuant alhora, i convé distingir-los perquè es confonen:

• Idempotency-Key protegeix contra el reintent del mateix client: si la resposta es va perdre, repetir la petició retorna la resposta desada sense tornar a cobrar.
• If-Match protegeix contra l'escriptura sobre una versió obsoleta: si un altre procés ja ha canviat la comanda, respon 412 (04-06 i 03-05).
• La transició d'estat protegeix contra allò semànticament impossible: pagar dues vegades amb claus diferents respon 409 comanda_ja_pagada.

I observa com canvien els _links: han desaparegut pagament i anullacio, i han aparegut factura i enviament. Els enllaços són la màquina d'estats.

El pagament dispara un esdeveniment. L'API no crida RàpidEnviaments dins de la transacció; encua l'esdeveniment i el lliura després, perquè un transportista lent no pot bloquejar un cobrament.

La signatura és HMAC-SHA256 del cos cru amb el secret compartit. RàpidEnviaments la verifica, respon 2xx i encua la seva feina. Si respon 5xx o no respon, ho reintentem amb espera exponencial. Aroma-Esdeveniment-Id permet a RàpidEnviaments descartar duplicats: el lliurament és "com a mínim una vegada", així que el receptor ha de ser idempotent.

Quan RàpidEnviaments recull el paquet, un empleat (o la seva integració) marca l'enviament:

La Marta consulta l'estat. Com que sondeja cada minut, la memòria cau condicional fa la seva feina:

I la factura, que és un recurs amb una altra representació:

immutable perquè una factura emesa no canvia mai. És un dels pocs llocs de tota l'API on aquesta directiva està plenament justificada.

Un disseny es jutja pel que fa quan les coses van malament. Aquests sis casos són els que de debò van costar reunions.

El problema. Queden 2 unitats de caf_001 i dos clients creen una comanda de 2 en el mateix instant. Si comprovem l'estoc i després el descomptem en dos passos separats, tots dos llegeixen 2, tots dos veuen que n'hi ha prou i tots dos venen. Sobrevenda.

La solució. Tot dins d'una transacció, i el descompte amb la condició incorporada a la mateixa sentència:

La comprovació i l'escriptura són la mateixa operació atòmica. Si changes() retorna 0, no hi havia estoc i es llança l'error:

Per què 409 i no 400. El 400 diu "la teva petició està mal escrita"; reenviar-la igual sempre fallarà. El 409 diu "la teva petició és vàlida però xoca amb l'estat actual"; demà, amb l'estoc reposat, la mateixa petició funcionarà. La diferència importa per al client, que en el segon cas pot oferir "avisa'm quan n'hi hagi".

El problema. El mòbil de la Marta perd cobertura just després d'enviar POST /pagament. El servidor cobra; la resposta no arriba. L'app ho reintenta. Es cobra dues vegades?

La solució, en dues capes.

La primera és la Idempotency-Key. Abans de processar, s'intenta inserir la clau en una taula amb restricció única, juntament amb l'empremta del cos:

El reintent retorna la mateixa resposta desada, amb el mateix 201/200 i el mateix cos. No es cobra dues vegades.

La segona capa és la màquina d'estats: si arriba un pagament amb una clau nova sobre una comanda que ja està pagat, respon 409 comanda_ja_pagada. La idempotència cobreix el reintent; l'estat cobreix l'error genuí.

El problema. La Marta crea la comanda a les 9:14 amb caf_001 a 14,50 €. A les 9:20, un administrador puja el preu a 15,90 €. La Marta paga a les 9:25. Quant paga?

La solució: preu congelat a la línia. Cada línia de comanda desa el seu propi preu_centims, copiat del catàleg en el moment de la creació. La comanda no consulta el preu del cafè ni en mostrar-se ni en pagar-se.

Fixa't que també es copia el nom. No és redundància per descuit: si el cafè es reanomena o es retira del catàleg, la factura de la Marta ha de continuar dient què va comprar. Una comanda és un document històric, no una vista de dades actuals, i aquesta distinció canvia com es modela la taula.

La conseqüència que cal assumir: una cistella vella pot mostrar preus desactualitzats. Es va resoldre recalculant els preus de la cistella a cada GET /cistelles/{id} (la cistella sí que és una vista actual) i avisant a la interfície si alguna cosa havia canviat des de l'última visita.

El problema. Pot cli_842 ressenyar caf_002 si no l'ha comprat mai?

La decisió de negoci va ser: sí, però amb distinció visible. Ressenyar és una barrera baixa a propòsit, perquè el volum de ressenyes importa comercialment. Però una ressenya d'un comprador verificat val més.

La solució tècnica. En crear la ressenya, el servei consulta si existeix alguna comanda pagada d'aquest client que contingui aquest cafè, i segella el resultat al recurs:

I una regla afegida: una ressenya per client i cafè, amb restricció única a la base de dades. Un segon intent respon 409. Aquesta regla viu a l'índex, no només al servei, perquè amb dues instàncies de l'API en paral·lel la comprovació en codi no n'hi ha prou.

El problema. La Marta exerceix el seu dret de supressió (RGPD, article 17). Però les seves comandes són documents comptables que la legislació mercantil obliga a conservar uns quants anys. Dues obligacions legals que apunten en direccions oposades.

La solució: anonimitzar, no esborrar. DELETE /clients/cli_842 no executa cap DELETE a la taula. Substitueix les dades personals per valors neutres, conserva el registre amb el seu identificador i desactiva el compte:

La resposta és 204 No Content. A partir d'aquí, GET /clients/cli_842 respon 404 client_no_trobat a qualsevol que no sigui auditoria interna, i la comanda com_5001 continua existint amb el seu import, la seva data i el seu IVA, però sense cap persona al darrere.

Advertiment important. El que acabes de llegir és una solució tècnica plausible, no assessorament legal. Què es pot conservar, durant quant de temps, amb quina base jurídica i què compta com a anonimització efectiva —davant de la mera pseudonimització, que continua sent dada personal— depèn de la jurisdicció, del sector i del cas concret. En un projecte real, aquest disseny es valida amb el responsable de protecció de dades i amb assessoria jurídica abans d'escriure la primera línia de codi. També cal decidir què fer amb les còpies de seguretat, amb els logs i amb els sistemes tercers als quals es va enviar la dada (aquí, RàpidEnviaments), i això rarament ho resol un UPDATE.

El problema. Enviem comanda.pagada i no arriba resposta. El van rebre? El van processar? No hi ha manera de saber-ho des de fora.

La solució: cua persistent amb reintents i desactivació. L'esdeveniment es desa en una taula amb el seu estat, i un procés el reintenta amb espera exponencial i jitter: 1 min, 2, 4, 8, 16, 32, 64 min. Després de set intents fallits passa a fallada_permanent, es dispara una alerta i l'esdeveniment queda disponible per a reenviament manual des del tauler.

Tres detalls que fan que això funcioni en producció:

• Aroma-Esdeveniment-Id estable entre reintents. El mateix esdeveniment es reintenta amb el mateix identificador, perquè el receptor pugui descartar duplicats. Si canviés, cada reintent semblaria un esdeveniment nou i RàpidEnviaments crearia set enviaments.
• Lliurament "com a mínim una vegada", mai "exactament una vegada". És impossible garantir el segon sobre una xarxa no fiable, i prometre-ho a la documentació és enganyar. El que es documenta és: reintentem; sigues idempotent.
• Curtcircuit. Si RàpidEnviaments porta 50 fallades seguides, es deixa d'intentar durant uns minuts en comptes de castigar un servei que ja és caigut.

Cada peça és on és per una raó concreta:

Per què la idempotència viu a Redis i no en memòria. Amb tres instàncies darrere del gateway, el reintent del mòbil de la Marta pot aterrar en una instància diferent de l'original. Una memòria cau en memòria no ho veuria i tornaria a cobrar. És el mateix raonament que va portar el rate limiting a Redis a 04-04: qualsevol estat compartit entre peticions ha de viure fora del procés, o l'escalat horitzontal el trenca en silenci.

Els SLO es deriven dels requisits de l'apartat 3, i cadascun té el seu indicador mesurable (04-07):

I les alertes que de debò desperten algú de nit —deliberadament poques, perquè una alerta que sona sense conseqüència entrena l'equip a ignorar-les—:

CompresFallant dispara amb un sol error, mentre que la taxa general tolera un 1 %. Aquesta asimetria és intencionada i reflecteix la de l'apartat 3: no tots els endpoints valen el mateix.

Cap memòria tècnica honesta no acaba sense aquesta secció. Quatre decisions que, amb el projecte ja en producció, no repetiríem.

Què vam fer. {"dades": [...], "total": 42}.

Què va fallar. L'embolcall va ser encertat —va deixar lloc per a metadades— però es va quedar a mitges. Les metadades de paginació van acabar repartides entre la capçalera Link i el camp total, i cada consumidor va haver d'aprendre un lloc diferent per a cada cosa. Pitjor: total obliga a un COUNT(*) a cada llistat, que a /comandes amb filtres amplis és la consulta més lenta de tota l'API. I en una col·lecció paginada per cursor, un total exacte és a més conceptualment dubtós.

Què faríem. Un objecte meta explícit, i total opcional sota demanda:

Cost d'arreglar-ho ara. És un canvi trencador per als cinc consumidors. Va a la llista de la v2, i aquest és exactament el tipus de deute de contracte que es tracta a 06-03.

Què vam fer. Format propi: {"error": {"codi", "missatge", "detalls"}}.

Què va fallar. És un format raonable, coherent i ben documentat. Però és nostre. Existeix un estàndard, la RFC 9457, amb type, title, status, detail i instance, que les biblioteques de client, els gateways i les eines de monitoratge ja entenen. En integrar CataBox vam haver d'explicar el nostre format des de zero i escriure un adaptador; amb problem+json hauria estat una línia de configuració. I el Content-Type hauria estat autodescriptiu, que és justament la restricció de REST que més ens agrada citar (01-04).

Què faríem. problem+json amb extensions pròpies, que l'estàndard permet:

La lliçó general: abans d'inventar un format, comprova si ja n'existeix un d'estàndard. Que el teu sigui coherent no compensa que el món sencer parli un altre idioma.

Què vam fer. POST /cafes/{id}/ressenyes per crear, GET /ressenyes per moderar, GET /cafes/{id}/ressenyes per llistar les d'un cafè.

Què va fallar. Vam acabar amb dues rutes per al mateix recurs, i això es paga en llocs inesperats: dues entrades a l'OpenAPI que cal mantenir sincronitzades, dues rutes a les mètriques per ruta —cosa que dificulta respondre "quantes ressenyes es creen al dia?"—, dues regles de rate limiting, dues rutes al gateway, dos conjunts de proves. Quan va arribar POST /ressenyes/{id}/respostes, l'asimetria es va fer evident: les respostes pengen de la ressenya plana, no del cafè. I algun client va començar a fer servir GET /ressenyes?cafeId=caf_001, que retorna el mateix que GET /cafes/caf_001/ressenyes però amb una altra manera de paginar.

Què faríem. Col·lecció plana /ressenyes com a única font, amb POST /ressenyes incloent cafeId al cos, i GET /cafes/{id}/ressenyes conservat només com a drecera de lectura documentada com a tal —o eliminat, substituït per GET /ressenyes?cafeId=caf_001—.

El matís honest: hi ha un argument sòlid a favor del que vam fer, i és que POST /cafes/{id}/ressenyes fa impossible crear una ressenya sense cafè i deixa el cafeId fora del cos, on no es pot falsificar. No és una decisió òbviament dolenta; és una decisió el cost de la qual no vam valorar bé per endavant.

Què vam fer. L'estoc es comprova i es descompta només en crear la comanda.

Què va fallar. Al pic de Nadal, amb lots petits, van augmentar els 409 estoc_insuficient justament al pas final de la compra. Des del punt de vista de l'usuari, és la pitjor experiència possible: has arribat fins al pagament i llavors et diuen que no n'hi ha.

Què faríem. Mantenir la decisió de fons —reservar a la cistella porta més problemes dels que resol— però avisar abans: mostrar l'estoc restant a la cistella, avisar quan queden poques unitats i comprovar la disponibilitat en obrir el procés de compra, no només en confirmar-lo. L'error 409 continuaria existint, però deixaria de ser la primera notícia.

La lliçó general: alguns problemes de disseny d'API es resolen millor amb informació primerenca que amb més maquinària transaccional.

Confondre "acció" amb "recurs" al primer obstacle. Tan bon punt apareix una operació que no encaixa en CRUD, la temptació és POST /comandes/{id}/processarPagamentINotificar. Pregunta't quina cosa produeix o quin estat canvia. Gairebé sempre hi ha un substantiu al darrere: un pagament, una anul·lació, una devolució.

Coherència mal entesa. Fer servir el mateix model de paginació a tota l'API sona a bona pràctica, però a la Botiga Aroma hauria estat un error: el catàleg i les comandes tenen dinàmiques oposades. La coherència que importa és la de criteris, no la de mecanismes: "col·leccions petites i estables per desplaçament, col·leccions grans que creixen per davant per cursor" és una regla coherent que produeix dos mecanismes diferents.

Desar diners en flotants. 0.1 + 0.2 dona 0.30000000000000004. En una línia no es nota; en un total de campanya, sí. Cèntims com a enter per dins, cadena amb dos decimals per fora.

Una comanda que consulta el catàleg per mostrar preus. És l'error de modelatge més car d'aquest domini. Una comanda és història congelada; el catàleg és present. Copia el que necessitis, encara que sembli redundant.

Enviar webhooks dins de la transacció. Si la crida a RàpidEnviaments passa abans del COMMIT, una fallada posterior deixa notificada una comanda que no existeix. I si passa a dins, un transportista lent allarga la transacció i bloqueja la base de dades. Confirma primer, encua després.

Prometre "exactament una vegada" a la documentació de webhooks. No és realitzable sobre una xarxa no fiable. Documenta "com a mínim una vegada" i exigeix idempotència al receptor. És més honest i evita integracions trencades.

Consell: escriu la taula de decisions mentre dissenyes, no després. La columna que importa no és "què vam fer", que es dedueix del codi, sinó "què vam descartar i per què". D'aquí a un any, quan algú proposi canviar el model de paginació, aquesta columna evita repetir la discussió sencera.

Consell: fes el flux complet abans d'escriure codi. Escriure les deu peticions i respostes d'una compra en un fitxer de text, encadenades, revela buits que cap diagrama de recursos no mostra: capçaleres que falten, identificadors que ningú no va retornar, estats impossibles.

La Botiga Aroma vol llançar subscripcions: el client rep 500 g d'un cafè cada mes, la pot pausar, reprendre, canviar el cafè o cancel·lar-la, i cada mes es genera automàticament una comanda.

1. Decideix si "subscripció" és un recurs i justifica-ho amb les tres proves de l'apartat 4.
2. Dissenya el mapa d'URIs complet, incloent-hi pausa, represa, cancel·lació i consulta de les comandes generades.
3. Indica quins _links retornaries per a una subscripció en estat activa i en estat pausada.
4. Decideix el model de paginació de /subscripcions i justifica'l.

Escriu una prova d'integració que demostri la sobrevenda quan la comprovació d'estoc i el descompte van en dos passos separats, i verifica després que la solució de l'apartat 8.1 l'evita. Comprova també el codi i el cos de l'error.

Pren la taula de l'apartat 6 i, per a cadascuna d'aquestes tres files, argumenta el cas contrari de manera convincent: (a) _links selectius, (b) versió a la ruta, (c) identificadors amb prefix. Després decideix si mantindries la decisió original i per què. L'objectiu és distingir les decisions ben fonamentades de les que se sostenen només per costum.

Solució 1

1. És un recurs? Sí, sense dubtar-ho. Identitat: sub_301. Estat persistent: activa, pausada, cancellada, més la data de la propera entrega. Cicle de vida: llarg, amb transicions ben definides. Compleix les tres proves millor que la cistella.

2. Mapa d'URIs:

Pausar i reprendre són subrecursos amb POST, igual que /pagament: són transicions d'estat, no edicions de camps. Un PATCH {"estat":"pausada"} permetria saltar a qualsevol estat sense control.

Canviar el cafè sí que és PATCH, perquè és una edició d'un atribut, no una transició del cicle de vida. La distinció és exactament la de la decisió 1 de l'apartat 6.

3. Enllaços per estat:

Una subscripció cancellada només tindria self i comandes: és terminal.

4. Paginació: desplaçament. Un client té una, dues o tres subscripcions; ni el més entusiasta arribarà a vint. La col·lecció és minúscula, estable i es consulta sencera. El cursor afegiria complexitat sense resoldre cap problema. Diferent és /subscripcions/{id}/comandes, que creix cada mes durant anys i hereta el cursor de /comandes.

Solució 2

Com demostrar primer la fallada. Substitueix temporalment l'UPDATE ... WHERE estoc >= :quantitat per dos passos —SELECT estoc i després UPDATE estoc = :nou— fora de transacció. Amb la versió ingènua veuràs dos 201 i estoc = -2. Restaura la versió correcta i la prova passa. Aquesta prova és valuosa precisament perquè falla amb la implementació ingènua: una prova que passa amb el codi trencat no prova res.

Nota: amb SQLite i better-sqlite3 les escriptures se serialitzen, cosa que ja ajuda; amb PostgreSQL o MySQL, l'UPDATE ... WHERE condicional dins de la transacció és el que garanteix l'atomicitat. La condició a la sentència mateixa és el que és portable.

Solució 3

(a) Cas contrari als _links selectius. «La selectivitat obliga el servidor a calcular els enllaços a cada resposta, és més codi i més proves, i produeix una API inconsistent: uns recursos porten enllaços i d'altres no, cosa que confon qui la descobreix. A més, un client que vulgui saber si una comanda és anul·lable l'ha de demanar sencera. O HATEOAS complet, o cap i que el client conegui l'estat.» Veredicte: es manté. L'argument de la inconsistència és real, però es resol documentant-la, no eliminant el valor. Els enllaços de comanda eviten que cinc consumidors reimplementin —i desincronitzin— la mateixa màquina d'estats. Als cafès no hi havia res a evitar.

(b) Cas contrari a la versió a la ruta. «/v1/cafes/caf_001 i /v2/cafes/caf_001 són URI diferents per al mateix recurs, cosa que contradiu la identificació de recursos de 01-04. La versió és un detall de la representació i el seu lloc natural és Accept. Amb la versió a la ruta, cada client té enllaços fixats al codi i HATEOAS es torna impossible de versionar netament.» Veredicte: es manté, amb el cost reconegut. L'argument és teòricament correcte i l'assumim. A canvi: la versió apareix als logs, a les mètriques i a la configuració del gateway, es prova des del navegador, s'enruta sense lògica a l'aplicació i respon a "qui continua a la v1?" amb una consulta trivial. A 06-03 veuràs quant val això a l'hora de migrar.

(c) Cas contrari als identificadors amb prefix. «El prefix barreja el tipus amb l'identificador, es torna mentida quan un recurs canvia de tipus o es fusiona amb un altre, ocupa bytes a cada resposta i tempta els clients a analitzar l'identificador per deduir-ne el tipus, creant un acoblament amb un detall intern.» Veredicte: es manté. El risc de l'anàlisi és real i es mitiga documentant explícitament que l'identificador és opac. A canvi, cada missatge d'error, cada log i cada tiquet de suport es llegeixen sense consultar la base de dades, i això es cobra cada dia.

Una llista aplicable a qualsevol API que dissenyis, derivada de tot el que hem recorregut:

Disseny

• [ ] Els consumidors estan identificats, i cadascun amb la seva necessitat concreta.
• [ ] Els recursos surten del domini, no de les taules.
• [ ] URI en plural, sense verbs, amb imbricació màxima de dos nivells.
• [ ] Cada mètode HTTP respecta la seva semàntica: GET segur, PUT/DELETE idempotents.
• [ ] Els codis d'estat distingeixen 400, 409, 412, 422 i 429 amb criteri.
• [ ] Catàleg d'errors tancat, documentat i amb codis estables.
• [ ] Model de paginació triat per domini i justificat per escrit.
• [ ] Estratègia de versionat i política de deprecació publicades.

Implementació

• [ ] Validació de tota l'entrada a la vora, amb esquemes.
• [ ] Transaccions on hi ha invariants; condicions dins de la sentència.
• [ ] Concurrència optimista amb versio i ETag/If-Match on importa.
• [ ] Idempotència en tota operació amb efectes de diners o de tercers.
• [ ] Errors unificats per un únic gestor.
• [ ] Diners en enters; dates en ISO-8601 UTC.
• [ ] Dades històriques copiades, no referenciades.

Seguretat

• [ ] Autenticació i autorització per rol i per propietat del recurs.
• [ ] CORS amb llista blanca explícita; mai * amb credencials.
• [ ] Rate limiting amb estat compartit i 429 amb Retry-After.
• [ ] Secrets fora del codi; capçaleres de seguretat amb helmet.
• [ ] Dades personals minimitzades als logs, i esborrat amb criteri legal validat.

Operació

• [ ] Logs estructurats amb identificador de traça propagat.
• [ ] Mètriques dels senyals d'or i SLO acordats amb negoci.
• [ ] liveness i readiness diferenciats.
• [ ] Alertes poques i accionables, prioritzades per impacte de negoci.
• [ ] Memòria cau HTTP calibrada recurs a recurs.

Contracte i lliurament

• [ ] OpenAPI complet, validat amb Spectral i publicat.
• [ ] Proves unitàries, d'integració, de contracte i e2e a CI.
• [ ] Detecció automàtica de canvis trencadors.
• [ ] Desplegament sense tall amb migracions retrocompatibles i tornada enrere.
• [ ] Decisions importants registrades com a ADR, amb la seva alternativa descartada.

Has recorregut l'API de la Botiga Aroma sencera, dels requisits al desplegament, i sobretot has vist per què és com és. La cistella és recurs i el procés de compra no, perquè l'una té estat i l'altre és un procés. Els diners van en cèntims per dins i en euros per fora, perquè l'aritmètica i la llegibilitat demanen coses diferents. Els cafès es paginen per desplaçament i les comandes per cursor, perquè són col·leccions amb dinàmiques oposades i forçar un únic mecanisme hauria estat coherència mal entesa. La Idempotency-Key és al pagament perquè les xarxes mòbils reintenten soles i un timeout no diu si el servidor va cobrar.

Has vist també el que poques vegades s'ensenya: els casos difícils resolts amb nom i cognoms —la sobrevenda tancada amb una condició dins de l'UPDATE, el doble pagament tancat en dues capes, el preu congelat a la línia perquè una comanda és història i no una vista, l'anonimització del client amb l'advertiment que aquest disseny el signa un jurista i no un programador, i els webhooks lliurats "com a mínim una vegada" perquè prometre més seria mentir—. I una autocrítica honesta: l'embolcall que es va quedar a mitges, el problem+json que hauríem hagut de fer servir, les ressenyes amb dos camins i l'estoc que avisava massa tard. Aquest és el material de què estan fetes les memòries tècniques útils: no la llista d'encerts, sinó la de bifurcacions amb el seu preu.

El risc d'una lliçó així és treure'n la conclusió equivocada: creure que ja tens la plantilla d'una API REST i que n'hi ha prou de canviar cafes pel que toqui. No és així. Cada decisió d'aquesta lliçó és correcta per a aquest domini: un catàleg petit i estable, estoc finit i transaccional, poques escriptures d'altíssim valor, cinc consumidors coneguts i consistència forta com a requisit irrenunciable. Canvia el domini i unes quantes d'aquestes decisions deixen de sostenir-se.

Això és exactament el que fa la lliçó següent. A 06-02, Cas d'estudi: API d'una xarxa social, dissenyem CafeSocial, la xarxa de tastadors que la Botiga Aroma vol llançar, i unes quantes certeses d'avui cauen una a una: el graf de seguidors obliga a modelar la relació com a recurs; la línia de temps no és una col·lecció normal sinó un recurs derivat amb el problema del fan-out al darrere; la paginació per desplaçament deixa de funcionar directament —duplicats i salts— i el cursor opac passa d'opció a obligació; els comptadors de "m'agrada" es tornen aproximats a propòsit; les imatges ja no es pugen per l'API; l'autorització deixa de ser "de qui és això" per convertir-se en "qui pregunta i què li deixem veure", amb 404 on la botiga responia 403; i el temps real deixa de ser un extra del tauler per ser el producte. Acabarem amb la taula que dona sentit als dos casos junts, decisió a decisió, i amb el motiu que en aquell domini GraphQL sigui una alternativa molt més defensable del que era aquí.