Escena Viva ja és ràpida i està mesurada. El que li queda no és un problema de rendiment, sinó de disseny. La seva API va créixer per acumulació, mòdul a mòdul: primer un servidor artesanal al M4, després rutes d'Express al M6, després autenticació al M8. Pel camí van aparèixer verbs a les URL, codis d'estat triats a ull, llistats sense paginació, cap política de versions, i un dubte que vam deixar explícitament obert al mòdul 4: què passa quan Marc envia dues vegades el mateix POST /api/comandes perquè va perdre la cobertura a l'estrena del Festival de Jazz. Aquesta lliçó converteix aquella API en una API ben dissenyada, amb criteris justificats i no per gust estètic: una API és un contracte que altres programen al damunt i que no pots trencar quan vulguis.

1. Què és REST de debò
2. El model de maduresa de Richardson i HATEOAS
3. Disseny de recursos i accions que no són CRUD
4. Mètodes HTTP i les seves garanties
5. La clau d'idempotència
6. Codis d'estat fets servir amb criteri
7. Format de la resposta i dels errors
8. Paginació, filtratge, ordenació i selecció de camps
9. Versionat i política de deprecació
10. Memòria cau HTTP i peticions condicionals
11. Documentació amb OpenAPI
12. Redisseny de l'API d'Escena Viva

REST (Representational State Transfer) és un estil arquitectònic descrit per Roy Fielding a la seva tesi doctoral de l'any 2000. No és un format, no és JSON i no és "fer servir verbs HTTP": són sis restriccions.

La restricció sense estat és la que més conseqüències pràctiques té i la que més s'incompleix. És literalment la que fa possible tot el mòdul 10: si cada petició es basta a si mateixa, qualsevol dels set treballadors de la lliçó 10-01 pot atendre-la, i per això el repartiment SCHED_RR funciona. Quan a la 10-03 vam moure les sessions a Redis, el que vam fer va ser externalitzar l'estat perquè el servidor continués sent intercanviable. Un servidor amb estat en memòria no escala horitzontalment: és el mateix aprenentatge vist des de l'altre costat.

Leonard Richardson va proposar una escala de quatre nivells per situar-se amb honestedat:

Gairebé cap API anomenada REST no passa del nivell 2, i convé dir-ho sense dramatisme: el nivell 2, ben fet, és un disseny excel·lent i és l'objectiu realista. HATEOAS (Hypermedia as the Engine of Application State) significa que el client descobreix el que pot fer a partir de la mateixa resposta, en comptes de tenir les URL codificades:

El seu valor real és que els enllaços expressen l'estat: si la comanda ja està anul·lada, l'enllaç anullar no apareix, i el client no ha de replicar les regles de negoci per saber quin botó ha de mostrar. El motiu pel qual gairebé ningú no arriba al nivell 3 és que els clients reals (una aplicació React, una app mòbil) no naveguen per hipermèdia: tenen les rutes escrites al codi i no hi guanyen res. Recomanació pràctica per a Escena Viva: nivell 2 sòlid, amb enllaços on aporten (accions condicionades per l'estat i navegació de pàgines), sense fingir el nivell 3 amb enllaços self que ningú no fa servir ni renunciar als enllaços quan eliminen lògica duplicada al client.

Sobre la jerarquia, el criteri és la dependència d'existència. Una sessió no existeix sense el seu esdeveniment, així que /esdeveniments/evt-003/sessions és correcte per llistar-les; però una sessió concreta té identitat pròpia (ses-003-1) i també ha de ser accessible a /sessions/ses-003-1. La regla habitual: imbricar com a màxim un nivell per al llistat dins del pare, i exposar el recurs fill a la seva pròpia arrel per a l'accés directe, perquè jerarquies de tres o més nivells obliguen el client a conèixer tota la cadena d'identificadors per no res. I ara la pregunta difícil: com es modela anul·lar una comanda o publicar un esdeveniment? No són creacions ni esborrats, són transicions d'estat, i hi ha tres opcions legítimes més una que no ho és:

A Escena Viva triem la primera per anul·lar, i el motiu és concret: l'anul·lació és una entitat de negoci, amb motiu, data, import reemborsat i qui la va sol·licitar, que administració voldrà consultar. GET /api/v1/comandes/ped-77/anullacio retorna aquest registre, i això no seria possible amb un PATCH. Per publicar un esdeveniment, en canvi, fem servir PATCH, perquè és un simple canvi de camp sense dades associades.

Cada mètode té tres propietats que l'estàndard defineix i que la infraestructura d'internet dona per bones: proxies, navegadors i biblioteques client reintenten mètodes idempotents automàticament.

Les definicions exactes importen. Segur significa que no modifica l'estat del servidor: un GET que esborra alguna cosa és una fallada greu, perquè qualsevol rastrejador o precarregador del navegador l'activarà. Idempotent significa que executar-lo N vegades deixa el sistema igual que executar-lo una vegada: DELETE /esdeveniments/evt-009 dues vegades deixa l'esdeveniment esborrat i la segona retorna 404, però l'estat és el mateix; idempotència no significa "retorna el mateix". I cacheable significa que la resposta es pot emmagatzemar i reutilitzar. Quant a PUT davant de PATCH, PUT reemplaça el recurs complet (el que no enviïs s'esborra) i PATCH modifica parcialment; el problema és que PATCH no defineix el seu propi format, així que cal dir quin es fa servir:

application/merge-patch+json (RFC 7386) és el format raonable: els camps presents s'assignen, i null significa "esborra aquest camp". El seu límit és que no pot posar un camp a null de debò ni modificar un element concret d'un array; per a això hi ha application/json-patch+json (RFC 6902), amb operacions explícites, molt més potent i molt més incòmode. Recomanació: merge-patch llevat que necessitis l'altre. I una nota sobre PATCH i idempotència: { "titol": "X" } sí que és idempotent a la pràctica; el que no ho són són les operacions relatives com { "incrementarAforament": 10 }, que convé evitar.

Aquí resolem el dubte del mòdul 4. Escenari real: a l'estrena del Festival de Jazz, Marc prem "Comprar 2 entrades per a ses-003-1". La petició arriba al servidor, es processa, es crea la comanda ped-77... i la resposta es perd perquè el mòbil ha canviat d'antena. El client reintenta. Es creen dues comandes i Marc paga dues vegades. Com que POST no és idempotent per definició, la infraestructura no ens pot ajudar, i la solució estàndard de la indústria (Stripe, PayPal, i ara un esborrany de l'IETF) és una capçalera:

El client genera la clau (un UUID) abans del primer intent i la reutilitza a tots els reintents d'aquella mateixa operació. El servidor la fa servir així:

Quatre decisions que mereixen justificació. L'empremta del cos impedeix que un client amb un error de programació reutilitzi la clau per a una altra compra. L'estat en-curs cobreix la carrera de dues peticions simultànies. Els errors 5xx no es memoritzen, perquè una fallada transitòria ha de poder reintentar-se. I el TTL de 24 hores acota el creixement sense deixar fora reintents raonables. Tot això es combina amb la idempotència del consumidor de la lliçó 10-03: la clau protegeix l'entrada a l'API, i el jobId protegeix l'execució del treball.

L'antipatró que cal erradicar és respondre 200 OK amb { "error": ... } a dins. Trenca tot el que hi ha entre el client i tu: els proxies desen un error a la memòria cau com si fos una resposta vàlida, les biblioteques client no llancen excepció, el monitoratge compta 0 % d'errors mentre el sistema crema, i els reintents automàtics no s'activen. El codi d'estat és part del missatge, no decoració. La distinció 400 / 422 és la que més dubtes genera: 400 si no he pogut entendre la petició (JSON trencat, capçalera absent); 422 si l'he entès perfectament però no la puc acceptar (quantitat: -3 és un número vàlid i una quantitat impossible), de manera que gairebé tots els errors de validació de zod (M6) són 422. El 409, per la seva banda, té un ús molt concret: intentar comprar 5 entrades quan en queden 3 no és un error de validació —5 és una quantitat perfectament vàlida— sinó un conflicte amb l'estat actual del recurs, i a més un error que pot desaparèixer si algú anul·la la seva comanda, cosa que el client ha de saber.

Embolcall o no? Retornar el recurs directament ({ "id": "evt-003", ... }) és net i és el que fa la majoria; un embolcall ({ "dades": ..., "meta": ... }) permet afegir metadades sense tocar el recurs. La incoherència és l'única cosa inacceptable. Decisió d'Escena Viva: recurs directe als detalls, embolcall a les col·leccions, perquè una col·lecció necessita metadades de paginació per força.

Errors. El RFC 9457 (Problem Details for HTTP APIs, que substitueix el 7807) defineix un format estàndard, servit amb Content-Type: application/problem+json:

Comparat amb el format propi d'Escena Viva:

La decisió honesta: mantenim el nostre format perquè hi ha clients que ja en depenen i trencar-lo seria una ruptura de contracte major, però hi afegim Content-Type: application/problem+json amb els àlies type, title i status com a camps addicionals, de manera que les eines estàndard entenguin la resposta i els nostres clients continuïn funcionant. És una convergència progressiva, no una migració de cop; si comencessis avui des de zero, fes servir RFC 9457 directament. I una regla de seguretat heretada del M8: l'error no filtra mai detalls interns —res de piles de crides, noms de taula ni SQL—, sinó que inclou l'idPeticio (del middleware id-peticio.js) perquè l'usuari el pugui citar al suport i tu el puguis correlacionar amb el registre.

Per a la paginació hi ha dues escoles:

L'argument decisiu és el de les dades canviants: si Lucía mira la pàgina 1 del catàleg ordenat per vendes, es venen entrades i després demana la pàgina 2, amb offset veurà elements repetits i se'n saltarà d'altres, perquè l'ordre ha canviat sota els seus peus. Amb cursor això no passa, perquè codifica una posició estable dins l'ordre.

Recomanació pràctica: cursor per al catàleg públic (gran, canviant, navegació seqüencial) i offset per al panell d'administració (on l'organitzador de la Sala Bóveda sí que vol saltar a la pàgina 7 i veure el total). I en tots dos casos, límit màxim imposat pel servidor: limit=100000 no pot ser una manera de tombar l'API. Amb la mateixa coherència es defineix la gramàtica de consulta, un sol criteri per a tota l'API:

Tot això es valida amb zod (M6), amb llista blanca de camps ordenables i expandibles: sense ella, ?ordre=columnaSecreta és una fuita d'informació i ?incloure=tot és una denegació de servei. La selecció de camps, a més, és una optimització real, perquè redueix el JSON serialitzat que la lliçó 10-04 va identificar com un consumidor de CPU important.

Tres formes, amb els seus compromisos:

Recomanació: a la ruta. És la que fan servir Stripe, GitHub i pràcticament tothom, per una raó pragmàtica: és l'única que un desenvolupador entén sense llegir documentació, i l'única que funciona bé amb proxies i memòries cau. I un advertiment: versionar és car, perquè cada versió viva és codi que cal mantenir i provar. Canvia dins de v1 sempre que el canvi sigui additiu (camps opcionals nous, punts d'entrada nous) i reserva v2 per a ruptures reals: treure un camp, canviar un tipus, canviar el significat d'alguna cosa. Quan toqui deprecar, hi ha capçaleres estàndard:

Deprecation indica des de quan és obsolet; Sunset (RFC 8594) quan deixarà de funcionar. Un calendari raonable: anunci, sis mesos de convivència amb avisos, un "dia d'apagada" de prova (unes hores de respostes 410 perquè els clients ressagats se n'assabentin), i retirada. I una cosa que s'oblida: mesura l'ús de cada versió per client, perquè sense aquesta dada apagar v1 és un salt al buit.

Al mòdul 4 vam implementar ETag i 304 a mà sobre node:http; ara ho apliquem amb criteri i ho combinem amb la memòria cau de Redis de la lliçó 10-03.

Tenim ara tres capes de memòria cau encadenades: Cache-Control al navegador (la petició ni tan sols surt), ETag/304 al servidor (la petició surt però no es transfereix el cos) i Redis (10-03), que evita recalcular i consultar PostgreSQL. Regla de seguretat crítica: les dades privades porten Cache-Control: private, no-store. Un public a la resposta de GET /api/v1/comandes/ped-77 permetria que un proxy compartit desés les comandes de Lucía i les servís a un altre usuari. I sempre Vary: Authorization a les respostes que depenen de l'usuari. Peticions condicionals per evitar l'actualització perduda. Escenari: dos organitzadors de l'Auditorio Ribera editen evt-003 alhora. Tots dos llegeixen la versió actual, tots dos escriuen; el segon trepitja els canvis del primer sense que ningú se n'assabenti. És l'actualització perduda (lost update), i HTTP la resol amb control de concurrència optimista:

Un middleware crearExigirIfMatch({ obtenirEtiqueta }) ho implementa en tres comprovacions: si falta la capçalera If-Match, respon 428 (Precondition Required), que li diu al client que la seva petició està ben formada però que l'API exigeix una condició; si el recurs no existeix, 404; i si l'etiqueta rebuda no coincideix amb l'actual (i no és *), llança ErrorDApi('CONFLICTE_DE_VERSIO', 412).

Una API sense documentació no es pot fer servir; una API amb documentació escrita a mà menteix, perquè ningú no l'actualitza quan canvia el codi. La solució és que el contracte i el codi comparteixin una única font, i a Escena Viva ja tenim aquesta font: els esquemes zod de src/esquemes/ que validen cada petició. Amb zod-to-openapi es converteixen en el document OpenAPI, amb la garantia que el que està documentat és exactament el que es valida.

Així el contracte esdevé verificable en comptes d'una promesa: a les proves d'integració del mòdul 9 es pot validar cada resposta contra l'esquema OpenAPI, de manera que una resposta que es desvia del contracte trenca la construcció. Aquesta és la diferència entre documentació i contracte.

• Verbs a les URL (/obtenirEsdeveniments, /comprarEntrades): el verb va al mètode HTTP.
• 200 amb un error a dins. Trenca proxies, clients, reintents i monitoratge.
• GET que modifica, o llistats sense límit màxim: en el primer cas un precarregador pot esborrar dades per tu, en el segon ?limit=1000000 és una denegació de servei amb paràmetres.
• Confondre 401 amb 403. 401 = no sé qui ets. 403 = sé qui ets i no pots.
• Cache-Control: public en dades privades. Un proxy compartit pot servir les comandes de Lucía a un altre usuari.
• Versionar per costum, o escriure la documentació a mà: la primera és manteniment evitable, la segona es desincronitza en setmanes.
• Consell: als POST que cobren, exigeix Idempotency-Key i respon 400 si falta. És més segur que fer-la opcional.
• Consell: afegeix una prova d'integració per cada codi d'estat documentat. Si documentes un 409, demostra'l.

Aplica el middleware d'idempotència a POST /api/v1/comandes. Escriu una prova d'integració (M9) que enviï la mateixa petició dues vegades amb la mateixa Idempotency-Key i verifiqui: una sola comanda creada, mateixa resposta i Idempotent-Replay: true a la segona. Afegeix un cas amb la mateixa clau i cos diferent.

Implementa GET /api/v1/esdeveniments amb cursor sobre (dataInici, id). Prova: demana la pàgina 1 amb limit=2, insereix un esdeveniment nou amb data anterior, demana la pàgina 2 i comprova que no es repeteix ni es perd cap element. Repeteix-ho amb offset i compara.

Afegeix ETag a GET /api/v1/esdeveniments/:id i exigeix If-Match al PATCH. Simula dos organitzadors editant evt-003: tots dos llegeixen, el primer escriu amb èxit, el segon escriu amb l'etiqueta antiga. Verifica el 412 i dissenya la resposta d'error perquè el client sàpiga què ha de fer.

Exercici 1. La primera petició retorna 201 amb Location: /api/v1/comandes/ped-77. La segona retorna exactament el mateix cos i el mateix 201, amb Idempotent-Replay: true, i Comanda.count() continua sent 1. El punt subtil és que la resposta repetida és 201, no 200: es repeteix la resposta original tal qual, perquè el client no ha de distingir un reintent d'un primer intent. Amb la mateixa Idempotency-Key i un cos diferent, l'empremta no coincideix i es retorna 422 amb CLAU_IDEMPOTENCIA_REUTILITZADA: és un error del client, no una compra nova. Per a la carrera de peticions simultànies, SET NX garanteix que només una guanya i l'altra rep 409 amb Retry-After: 2.

Exercici 2. Amb cursor, la pàgina 2 continua exactament on va acabar la 1: l'esdeveniment nou amb data anterior no apareix (queda "darrere" del cursor) i cap element no es duplica. Amb offset, l'esdeveniment nou desplaça tot cap endavant i l'últim element de la pàgina 1 reapareix com a primer de la pàgina 2. És una fallada silenciosa que al catàleg del Festival de Jazz significaria mostrar la mateixa sessió dues vegades i amagar-ne una altra. Detall imprescindible: el cursor ha d'incloure el desempat per id; amb només dataInici, dos esdeveniments de la mateixa data provoquen el mateix problema que volies evitar.

Exercici 3. El primer PATCH amb If-Match: "v7-a3f2c1" coincideix i retorna 200 amb un ETag nou. El segon, amb l'etiqueta antiga, rep 412. L'error ha de ser accionable:

Sense If-Match, el segon organitzador hauria trepitjat el canvi del primer: l'aforament d'evt-003 quedaria en el valor equivocat i ningú no ho sabria fins a la nit de l'estrena. Nota d'implementació: l'etiqueta ha de derivar de la versió del recurs (un camp versio incrementat a cada escriptura, o updatedAt), no del cos serialitzat, perquè el cos pot variar per selecció de camps o format.

L'API d'Escena Viva ha passat de "funciona" a "està ben dissenyada", i cada decisió té el seu motiu. Sabem què exigeix REST de debò —i que la restricció sense estat és exactament el que fa possible l'escalat de la lliçó 10-01—, on ens situa el model de Richardson i per què el nivell 2 sòlid amb enllaços selectius és l'objectiu realista. Modelem recursos amb substantius plurals i jerarquies justificades, i les accions que no són CRUD com a subrecursos amb entitat pròpia. Coneixem les garanties de cada mètode HTTP, la diferència entre PUT i PATCH amb merge-patch, i hem tancat per fi el dubte del mòdul 4 amb la clau d'idempotència, que impedeix que Marc pagui dues vegades quan perd la cobertura. Fem servir els codis d'estat amb criteri (201 amb Location, 202 per al treball encuat, 409 per a l'aforament, 422 per a la validació) i hem bandejat el 200 amb un error a dins. Convergim cap a problem+json sense trencar els nostres clients. Paginem per cursor on les dades canvien, amb una gramàtica de consulta coherent i límits imposats pel servidor. Versionem a la ruta amb una política de deprecació amb dates. Encadenem tres capes de memòria cau i evitem l'actualització perduda amb If-Match i 412. I generem la documentació des dels esquemes zod, perquè el contracte no pugui mentir. Amb tot això, queda una pregunta que cap d'aquestes millores no respon: la pantalla d'un esdeveniment a l'aplicació d'Escena Viva continua necessitant tres crides (l'esdeveniment, les seves sessions, la sala), o una sola resposta amb molts camps que aquell client no fa servir. El disseny REST no elimina aquest dilema, només l'administra. A la lliçó següent, GraphQL amb Node.js, veurem una alternativa on el client demana exactament el que necessita, quin preu es paga per això —memòria cau, complexitat, límits de consulta— i per què la resposta correcta gairebé mai no és substituir REST, sinó fer que convisquin.