El mòdul de disseny va acabar amb una llista de preguntes pendents, i la primera era la més concreta: com es parlen exactament els serveis. Tenim decidit que POST /comandes respon 202 Accepted, que Comandes consulta el catàleg amb GET /productes?ids=, que Inventari exposa POST /reserves; però un contracte no és un nom de ruta: és la forma exacta de la petició, la resposta, els codis d'estat, el format dels errors i les capçaleres que totes dues bandes es comprometen a respectar. Aquesta lliçó converteix aquelles decisions de disseny en contractes REST complets.

REST és l'estil de comunicació síncrona que TechCorp farà servir en dos llocs: a l'API pública (allò que la web i l'app mòbil consumeixen a través del gateway del port 8080) i a les poques crides síncrones internes que 02-02 va deixar autoritzades (Comandes → Catàleg i Comandes → Clients). Veurem com es modelen recursos i URIs, la semàntica dels verbs i la seva idempotència, els codis d'estat que farem servir durant tot el curs, els cinc contractes clau de TechCorp amb exemples de petició i resposta, un format d'error uniforme basat en l'RFC 7807, paginació, filtratge, HATEOAS a nivell pràctic, capçaleres útils, documentació amb OpenAPI 3 i, finalment, un endpoint Express i un client fetch mínims que apliquen el contracte. El versionat es deixa per a 03-06, el gateway per a 03-04 i la resiliència (reintents, circuit breakers) per a 06-03: aquí només apareix el timeout com a bona pràctica mínima.

1. REST en microserveis: què és i què no és
2. Recursos i URIs
3. Verbs HTTP, semàntica i idempotència
4. Codis d'estat que farem servir
5. Els contractes REST clau de TechCorp
6. Format d'errors uniforme: RFC 7807
7. Paginació, filtratge i ordenació
8. HATEOAS a nivell pràctic
9. Capçaleres útils
10. Documentació amb OpenAPI 3
11. Un endpoint Express i un client fetch que apliquen el contracte

REST (Representational State Transfer) no és un protocol ni una llibreria: és un conjunt de restriccions de disseny sobre HTTP. Les que ens importen en microserveis són quatre:

• Recursos identificats per URIs. Una comanda és /comandes/com-88213; un producte, /productes/p-501. La URI identifica la cosa, no l'acció.
• Manipulació mitjançant representacions. El client no toca la fila de PostgreSQL: envia i rep representacions (JSON) del recurs.
• Interfície uniforme. Els verbs HTTP (GET, POST, PUT, PATCH, DELETE) tenen el mateix significat a tots els serveis. Ningú no s'inventa POST /comandes/obtenir.
• Sense estat entre peticions. Cada petició porta tot el que cal (autenticació, identificadors). Això és el que permet tenir vuit rèpliques de Catàleg darrere d'un balancejador (03-05) sense que importi quina respon.

El que REST no és: no és "qualsevol cosa que retorni JSON per HTTP". La diferència entre una API REST i una API "RPC sobre HTTP" és en l'ús de la interfície uniforme, i en microserveis importa perquè el contracte REST és l'única frontera entre equips: si l'equip de Comandes (el Luis) pot endevinar com es comporta un endpoint de Catàleg només llegint-ne la URI i el verb, hi ha menys reunions, menys documentació i menys sorpreses.

Les regles de TechCorp per anomenar URIs, alineades amb el principi de 02-01 que "els contractes expressen negoci":

Un cas que confon: accions que no encaixen en un verb. Com es cancel·la una comanda? Hi ha dues opcions respectables:

• Tractar la cancel·lació com un canvi d'estat: PATCH /comandes/com-88213 amb {"estat": "CANCELLADA"}. Senzill, però barreja en un mateix endpoint canvis molt diferents.
• Modelar l'acció com un subrecurs: POST /comandes/com-88213/cancellacio. Crea "una cancel·lació" de la comanda, amb el seu propi cos (motiu) i la seva pròpia validació. És la que farà servir TechCorp, perquè la saga de 02-05 tracta la cancel·lació com un fet de negoci amb motiu, no com l'edició d'un camp.

El que no farem mai és POST /comandes/com-88213/cancellar amb el verb a la URI, ni exposar l'estructura interna: /comandes/com-88213/linies sí, /linies_comanda?comanda_id= no.

Cada verb té un significat i dues propietats que en sistemes distribuïts són crítiques: si és segur (no modifica estat) i si és idempotent (repetir-lo N vegades té el mateix efecte que fer-ho una sola vegada).

Per què importa la idempotència: a 01-02 vam veure que la xarxa no és fiable. Si Comandes crida PUT /clients/c-1024/adreca i la resposta es perd, pot repetir la crida sense por: l'adreça quedarà igual. Si repeteix un POST /reserves que ja s'havia processat, hi haurà dues reserves i l'estoc de p-501 baixarà dues vegades. Per això, a 02-05 vam introduir la capçalera Idempotency-Key per a POST /comandes: converteix un POST en repetible sense canviar-ne la semàntica. L'aplicarem igual a POST /reserves.

Sobre PATCH: {"preu": 54.90} és idempotent (repetir-lo deixa el mateix preu); {"incrementarEstoc": 5} no ho és. Regla de TechCorp: els PATCH descriuen l'estat desitjat, mai deltes.

No cal memoritzar els ~60 codis HTTP. TechCorp fa servir un subconjunt tancat, i tots els serveis l'apliquen igual (l'empaquetarem a @techcorp/comu-http, la llibreria tècnica de 02-02):

Dos matisos que TechCorp fixa per conveni perquè tots els equips responguin igual:

• 400 davant de 422. 400 és "no entenc la teva petició" (no és JSON, falta un camp, un número ve com a text). 422 és "l'entenc però no té sentit" (quantitat 0, data de lliurament en el passat). La distinció ajuda el client a saber si l'error és de serialització o de negoci.
• 404 davant de 409 en errors de negoci. Del monòlit heretem quatre errors: CLIENT_NO_EXISTEIX → 404, PRODUCTE_NO_DISPONIBLE → 400, SENSE_ESTOC → 409, PAGAMENT_REBUTJAT → 402. A l'arquitectura nova POST /comandes respon 202 abans de saber si hi ha estoc o si el pagament passa, de manera que SENSE_ESTOC i PAGAMENT_REBUTJAT deixen de ser respostes HTTP d'aquell endpoint i passen a ser motius de comanda.cancellada. SENSE_ESTOC continua sent un 409 de POST /reserves (Inventari). PRODUCTE_NO_DISPONIBLE passa a 422 (la petició és correcta, però demana una cosa que no està a la venda).

És el contracte més important del curs. Petició: el client envia només el que sap: què vol i on ho vol. No envia noms ni preus de producte (els congela Comandes consultant Catàleg, com fixa l'agregat de 02-03), ni el total (el calcula Comandes).

Resposta: 202 Accepted perquè, com vam decidir a 02-05, la saga (reserva d'estoc, cobrament, confirmació) continua en curs. Location diu on consultar el progrés. El cos retorna la comanda tal com ha quedat desada, amb els preus ja congelats i l'estat PENDENT.

Comportament amb Idempotency-Key: si el mateix client repeteix la petició amb la mateixa clau (perquè n'ha perdut la resposta), Comandes consulta claus_idempotencia (02-05) i retorna exactament la mateixa resposta, sense crear cap altra comanda. Si la clau es reutilitza amb un cos diferent, respon 422 amb codi CLAU_IDEMPOTENCIA_REUTILITZADA.

Errors possibles d'aquest endpoint (tots en el format de l'apartat 6):

És la lectura que segueix el 202: la web fa polling (o rep una notificació) fins que l'estat deixa de ser PENDENT.

Si la comanda no ha canviat des de la versió "v3", el servidor respon 304 Not Modified sense cos (estalvia amplada de banda en el polling). Si la comanda és d'un altre client, 403; si no existeix, 404.

És la crida síncrona interna més freqüent: Comandes necessita nom, preu i disponibilitat de cada línia per congelar-los. Dissenyar GET /productes/{id} i cridar-lo un cop per línia seria el clàssic problema N+1: una comanda de 20 línies serien 20 viatges de xarxa. Per això el contracte accepta un lot:

Decisions de contracte que convé explicar:

• Els ids que no existeixen no provoquen 404. Un lot és una consulta a la col·lecció; que en falti un dels ids no fa fallar la petició. Es retornen a noTrobats i és Comandes qui decideix què fer-ne (respondre 422 PRODUCTE_NO_DISPONIBLE).
• Límit de lot. Màxim 100 ids; per sobre, 400. Sense límit, algú acabaria demanant 5.000 productes en una URL.
• Cache-Control: max-age=30. El catàleg canvia poc; permetre 30 s de memòria cau al client redueix càrrega als pics ×20.
• Aquest JSON és el published language de 02-03; Comandes el tradueix amb el seu traductorProducte al seu propi model, de manera que si Catàleg canvia preu (ho veurem a 03-06), només canvia el traductor.

Comandes acostuma a resoldre el client a la seva rèplica local clients_ref (02-04), però quan la rèplica encara no el té (client acabat de registrar) fa aquesta crida:

Fixa't en el que no retorna: contrasenya, tokens, dades de pagament. La representació és una vista de negoci del client, no un bolcat de la taula.

A la saga per coreografia de 02-05, Inventari reserva estoc reaccionant a l'esdeveniment comanda.creada, no per una crida HTTP. Per a què serveix, doncs, un POST /reserves? Per tres motius: per al panell d'administració intern, per a proves, i perquè a 02-03 vam deixar oberta una relació partnership Comandes↔Inventari que en el futur podria passar a síncrona (gRPC a 03-03). Dissenyar el contracte ara costa poc i fixa el vocabulari.

Resposta quan hi ha estoc. Aquí sí que és 201, perquè la reserva queda feta en el mateix instant (una transacció local a la BD d'Inventari):

I quan no hi ha estoc, un 409 amb el detall de què falta (informació que la saga converteix en estoc.rebutjat):

Fer servir comandaId com a Idempotency-Key és deliberat: "una reserva per comanda" és exactament la garantia que volem.

Al monòlit, cada controlador retornava els errors com li semblava: de vegades {"error": "..."}, de vegades {"missatge": "..."}, de vegades HTML. Amb sis serveis i quatre equips, això es multiplica. L'RFC 7807 (Problem Details for HTTP APIs) defineix un format estàndard amb tipus MIME application/problem+json:

El camp codi és l'extensió que TechCorp estandarditza: un identificador estable en MAJUSCULES_AMB_GUIONS (CLIENT_NO_EXISTEIX, SENSE_ESTOC, PRODUCTE_NO_DISPONIBLE, PETICIO_INVALIDA, DADES_NO_VALIDES, DEPENDENCIA_NO_DISPONIBLE, VERSIO_OBSOLETA, CLAU_IDEMPOTENCIA_REUTILITZADA). Els clients fan switch sobre codi, mai sobre detail, que és text per a humans i pot canviar.

Exemple d'error de validació amb detall per camp (extensió errors):

Mapatge dels errors heretats del monòlit al model nou:

Un consell de seguretat: en un 500 el detail mai no inclou el missatge de l'excepció ni la traça (filtraria rutes, consultes SQL, noms de host). Es registra al log amb l'X-Request-Id i el client rep un detail genèric amb aquell identificador per poder-ho reportar.

Tota col·lecció que pugui créixer es pagina; GET /comandes sense límit acabaria retornant 3.000 comandes diàries acumulades durant anys.

Resposta paginada per cursor. El cursor és una cadena opaca (habitualment base64 de {creatEn, id} de l'últim element) que el client retorna tal qual:

Convenis de TechCorp per al filtratge i l'ordenació:

• Filtres com a paràmetres de query amb el nom del camp: ?estat=CONFIRMADA, ?clientId=c-1024. Rangs amb sufixos: ?creatDes=2026-08-01&creatFins=2026-08-15.
• Ordenació amb ordre=camp ascendent i ordre=-camp descendent; diversos camps separats per coma: ordre=-creatEn,id.
• limit amb valor per defecte (20) i màxim (100). Un client que en demana 10.000 rep 400.
• Només s'admeten els filtres i ordres documentats a OpenAPI; un paràmetre desconegut s'ignora (tolerància, que 03-06 formalitzarà), però un valor invàlid en un de conegut dona 400.

HATEOAS (Hypermedia As The Engine Of Application State) és la restricció de REST que diu que la resposta ha d'incloure enllaços a les accions possibles, de manera que el client "navegui" per l'API en lloc de construir URIs. Portat a l'extrem produeix APIs difícils de consumir i pocs l'apliquen del tot. TechCorp n'adopta una versió pragmàtica:

• Un objecte _links amb self sempre.
• Enllaços a accions que depenen de l'estat: una comanda PENDENT inclou cancellar; una de CONFIRMADA inclou factura però no cancellar. Així el front-end no duplica la màquina d'estats de 02-05 per saber quin botó ha de mostrar.
• Enllaços de paginació (seguent, anterior).
• Res més. No s'enllacen recursos d'altres serveis (una comanda no enllaça al /clients/{id} de Clients), perquè el client entra sempre pel gateway i les URIs internes no li serveixen.

Exemple de concurrència optimista: dos administradors editen el preu de p-501 alhora.

Si el producte ja és a la versió 13 perquè l'altre administrador ha desat abans, Catàleg respon 409 amb codi: VERSIO_OBSOLETA i el client recarrega i decideix. Sense If-Match, el segon desament trepitjaria el primer en silenci.

Un contracte que només viu al cap del Luis no és un contracte. OpenAPI 3 és l'especificació estàndard (YAML o JSON) per descriure APIs REST: rutes, paràmetres, cossos, respostes i esquemes. A partir d'ella es generen documentació navegable (Swagger UI, Redoc), clients, validadors de peticions i, a 04-05, proves. Fragment de l'especificació de Comandes i Catàleg:

I el lot de Catàleg, al seu propi document (cada servei publica el seu OpenAPI; no hi ha cap fitxer global):

Com es llegeix: paths agrupa rutes; dins de cada verb, parameters descriu query/capçaleres/ruta, requestBody el cos, i responses cada codi amb el seu esquema. components evita repetir esquemes i respostes. A 03-06 veurem que escriure aquest YAML abans del codi (design-first) és la manera que Comandes i Catàleg treballin en paral·lel.

Encara no muntem el servei complet (estructura, configuració i arrencada són del mòdul 4); només el tros que materialitza el contracte de POST /comandes.

Explicació pas a pas:

1. validarNovaComanda separa els dos nivells: si la forma és incorrecta retorna 400; si la forma és correcta però els valors no, 422 amb la llista de camps. És exactament la distinció de l'apartat 4.
2. respondreProblema centralitza el format RFC 7807. Al projecte real aquesta funció viu a @techcorp/comu-http perquè Catàleg, Inventari i la resta responguin idèntic.
3. La ruta comprova Idempotency-Key, valida, delega en el cas d'ús (que ja coneixem de 02-05: desa la comanda i el seu comanda.creada a la mateixa transacció amb desarAmbEsdeveniments()), i respon 202 amb Location. Fixa't que la ruta no sap res de RabbitMQ ni d'estoc: només tradueix HTTP a negoci i negoci a HTTP.
4. Els errors de negoci es mapen a codis del contracte; qualsevol altre va al middleware d'errors d'Express, que respon 500 sense filtrar detalls.

I el client: com Comandes crida el lot de Catàleg. Node.js 20 inclou fetch de manera nativa, i AbortSignal.timeout és la manera mínima de no quedar-se esperant per sempre.

Punts clau del client: la URL base ve de configuració (CATALEG_URL, amb un valor per defecte que és el nom estable del servei que justificarem a 03-05 i gestionarem a 04-03); es propaga X-Request-Id; hi ha un timeout de 2 s (sense ell, una caiguda de Catàleg esgotaria les connexions de Comandes); es distingeix "no ha respost" de "ha respost amb error"; i noTrobats es tradueix a l'error de negoci del contracte de POST /comandes. El que no hi ha aquí (reintents, circuit breaker, fallback) és matèria de 06-03.

• Verbs a les URIs (/comandes/crear, /productes/cercar). Si t'enxampes escrivint un verb, pregunta't quin és el recurs: gairebé sempre és una col·lecció (POST /comandes) o un subrecurs (POST /comandes/{id}/cancellacio).
• Retornar 200 per a tot i posar l'error al cos ({"ok": false}). Trenca la memòria cau HTTP, els monitors del gateway i la intuïció de qualsevol client. Fes servir la taula de l'apartat 4.
• 201 quan la feina no ha acabat. Si en respondre encara no saps si hi haurà estoc, és 202. Un 201 promet que el recurs és complet.
• N+1 per comoditat. GET /productes/{id} dins d'un bucle sembla net fins que una comanda de 15 línies triga 15 × 40 ms. Dissenya lots (?ids=) des del principi.
• Idempotency-Key sense persistència. Desar les claus en memòria del procés no serveix amb dues rèpliques: la taula claus_idempotencia de 02-05 és obligatòria.
• Missatges d'error com a contracte. Els clients han de mirar codi, no detail. Canviar un text no hauria de trencar ningú.
• Filtrar interns en errors 500. Mai detail: err.stack. Log complet amb X-Request-Id; al client, un missatge genèric amb aquell id.
• Oblidar el timeout al client. fetch sense signal espera indefinidament. Dos segons per a crides internes és un bon punt de partida.
• Documentar després. L'OpenAPI escrit a posteriori es desactualitza. Escriu-lo primer (03-06) i valida les peticions contra ell.

Exercici 1. Dissenya el contracte REST de "cancel·lar una comanda" per al servei de Comandes: URI i verb, cos de petició (amb motiu), respostes d'èxit i d'error amb els seus codis i codi, tenint en compte la màquina d'estats de 02-05 (només es pot cancel·lar en PENDENT, ESTOC_RESERVAT o PAGADA; no en CONFIRMADA ni si ja està CANCELLADA). Escriu un exemple http de petició i d'una resposta d'error.

Exercici 2. L'equip d'Experiència de compra proposa GET /clients/c-1024/comandes (al servei de Clients) perquè la web mostri l'historial de comandes d'un client. Raona si aquest endpoint ha de viure a Clients o a Comandes, quina URI proposaries, i quina estratègia de paginació (offset o cursor) triaries i per què. Escriu la resposta JSON de la primera pàgina amb dues comandes.

Exercici 3. Escriu una funció Express patch('/productes/:id') per a Catàleg que apliqui concurrència optimista amb If-Match. Suposa que existeix repositori.obtenir(id) que retorna { ...producte, versio } i repositori.actualitzarSiVersio(id, canvis, versioEsperada) que retorna el producte actualitzat o null si la versió no coincideix. Respon 428 Precondition Required si falta If-Match, 404 si no existeix, 409 VERSIO_OBSOLETA si la versió no coincideix i 200 amb un ETag nou si tot va bé.

Solució 1.

Contracte: POST /comandes/{id}/cancellacio. La cancel·lació és un fet de negoci amb dades pròpies (motiu, qui cancel·la), no l'edició d'un camp, i POST és el verb per a "crear un subrecurs". Ha d'acceptar Idempotency-Key (o, més senzill, ser idempotent per disseny: cancel·lar una comanda ja cancel·lada pel mateix motiu retorna 200 amb el mateix cos).

Respostes:

Es pot argumentar 200 en lloc de 202 si es considera que la comanda queda CANCELLADA de manera síncrona i les compensacions són un detall intern; totes dues opcions són defensables, però cal documentar la triada a OpenAPI i aplicar-la igual a tota l'API.

Solució 2.

Les comandes són del bounded context de Comandes (02-03): l'historial l'ha de servir el servei de Comandes, que és qui té les dades i el seu estat actualitzat. Posar l'endpoint a Clients obligaria Clients a consultar Comandes (acoblament innecessari) o a replicar comandes (que no li pertanyen). URI proposada: GET /comandes?clientId=c-1024&ordre=-creatEn&limit=20 a Comandes. La ruta imbricada /clients/{id}/comandes la pot oferir el gateway o el BFF (03-04) com a comoditat per al front, redirigint-la internament a Comandes, però el contracte canònic és el filtre sobre la col·lecció /comandes.

Paginació: cursor. L'historial d'un client creix per un extrem (les comandes noves entren a dalt), és una col·lecció potencialment gran i el cas d'ús és "scroll infinit" a la web i a l'app, no "anar a la pàgina 7". Amb offset, una comanda nova creada mentre l'usuari navega ho desplaçaria tot i repetiria un element entre pàgines.

Solució 3.

Punts que cal comprovar: l'ETag de resposta reflecteix la versió nova (13), de manera que un segon PATCH del mateix client pot encadenar-s'hi; i actualitzarSiVersio ha de fer la comprovació a la mateixa sentència SQL (UPDATE ... WHERE id = $1 AND versio = $2), no en dos passos, perquè la concurrència optimista sigui real.

Hem convertit les decisions de disseny del mòdul 2 en contractes REST concrets: URIs amb substantius i jerarquies, verbs amb la seva idempotència (i Idempotency-Key quan el verb no la té), una taula tancada de codis d'estat que tots els serveis apliquen igual, els cinc contractes clau de TechCorp (POST /comandes amb 202 + Location, GET /comandes/{id} amb ETag, GET /productes?ids= en lot per evitar l'N+1, GET /clients/{id}, POST /reserves amb 201/409), errors uniformes RFC 7807 amb el camp codi que substitueix els errors dispersos del monòlit, paginació per cursor per a col·leccions que creixen, HATEOAS mínim, capçaleres de memòria cau, concurrència optimista i correlació, OpenAPI 3 com a forma escrita del contracte, i una ruta Express i un client fetch amb timeout que l'apliquen.

REST cobreix les crides síncrones, però a 02-05 vam decidir que el cor del flux de comanda (reservar estoc, cobrar, confirmar, notificar) viatja per esdeveniments: comanda.creada, estoc.reservat, pagament.confirmat, comanda.confirmada, comanda.cancellada. Falta veure com es publiquen i es consumeixen de debò: què és un exchange i una cua a RabbitMQ, com s'encamina cada esdeveniment cap a qui li interessa, què passa quan un consumidor falla i com garantim que un esdeveniment no es perd ni es processa dues vegades. Això és la missatgeria asíncrona, la lliçó següent.