REST és l'estàndard de facto de les APIs web, però no és l'única eina ni sempre la millor. Els darrers anys han madurat alternatives que ataquen limitacions molt concretes: GraphQL va néixer del problema de demanar dades a mida des del mòbil; gRPC, de la necessitat de comunicació interna d'alt rendiment; els webhooks, de la incapacitat d'HTTP perquè el servidor avisi el client. Aquesta lliçó tanca el mòdul dibuixant el mapa complet d'estils d'integració, amb exemples aplicats a la Botiga Aroma, perquè sàpigues triar amb criteri i —el més important— entenguis que aquests enfocaments no competeixen: conviuen a la mateixa empresa, cadascun al seu lloc.

1. Per què no n'hi ha prou amb un únic estil
2. GraphQL: el client decideix quins camps vol
3. Quins problemes resol GraphQL i quins n'introdueix
4. gRPC: contracte fort i alt rendiment entre serveis
5. Comunicació dirigida per esdeveniments: webhooks
6. Cues, streaming i temps real: SSE i WebSockets
7. Taula comparativa dels quatre enfocaments
8. Criteris de decisió honestos
9. L'arquitectura final de la Botiga Aroma

Les necessitats de comunicació de la Botiga Aroma no són homogènies. Compara aquests quatre casos:

Cada desajust té una resposta específica. Veure-les juntes et dona criteri; fer-les servir totes alhora sense motiu, et dona una arquitectura ingovernable.

GraphQL és un llenguatge de consulta per a APIs, creat a Facebook el 2012 i publicat el 2015. Les seves tres decisions fonamentals:

1. Un esquema tipat defineix totes les dades disponibles i les seves relacions. És el contracte, i és obligatori.
2. Una sola URL (típicament /graphql), a la qual es fa POST.
3. El client escriu la consulta: demana exactament els camps que necessita, ni un més.

El signe ! vol dir "no pot ser nul". L'esquema és alhora documentació, validació i contracte: les eines el llegeixen i ofereixen autocompleció en escriure consultes.

L'app mòbil necessita, per a la seva pantalla de catàleg, només el nom, el preu i la puntuació mitjana. Ho demana així:

I rep exactament això, amb la mateixa forma que la consulta:

Per HTTP, la petició real és un POST:

Per aconseguir el mateix amb l'API REST de la Botiga Aroma caldrien diverses crides:

Onze peticions davant d'una, i a la primera es descarreguen origen, torrefaccio, estoc i notesTast que la pantalla no fa servir. Aquest és exactament l'argument de GraphQL.

Convé matisar-ho, en honor a la veritat: REST té respostes parcials a aquest problema —paràmetres d'expansió (?incloure=ressenyes), selecció de camps (?camps=nom,preuEuros) i endpoints agregats dissenyats per a una pantalla concreta—. El que passa és que en REST són convencions ad hoc que cada API resol a la seva manera, mentre que en GraphQL és el model mateix.

Fixa't en una cosa que ja saps reconèixer: GraphQL és, en termes de Richardson, un nivell 0 —un endpoint, tot per POST, l'operació dins del cos—. La diferència amb el pantà de POX és que aquí l'elecció és deliberada i ve acompanyada d'un contracte tipat, introspecció i un ecosistema d'eines que compensen el que s'hi perd.

gRPC (Google, 2015) és RPC modern. Els seus pilars:

• Protocol Buffers (protobuf): format binari compacte i tipat per serialitzar els missatges.
• HTTP/2 com a transport, amb multiplexatge i capçaleres comprimides.
• Contracte en un fitxer .proto del qual es genera el codi de client i de servidor en més de deu llenguatges.
• Quatre modes de comunicació, inclòs l'streaming en tots dos sentits.

Els números (= 1, = 2) no són valors: són les etiquetes de camp que ocupen el lloc dels noms al format binari. Per això protobuf és tan compacte —no envia els noms dels camps— i per això aquests números no s'han de canviar mai un cop publicats: són el contracte real.

Des de Node.js, el consum s'assembla a una crida a funció:

A favor: missatges molt més petits que JSON, serialització més ràpida, contracte fort amb generació de codi, streaming natiu, excel·lent per a trànsit intern d'alt volum i per a comunicació entre serveis escrits en llenguatges diferents.

En contra: no és consumible directament des d'un navegador (requereix una passarel·la com gRPC-Web), els missatges binaris no es llegeixen amb els ulls ni es depuren amb curl, no aprofita la memòria cau HTTP, i el tooling és pitjor fora d'entorns preparats. No és un bon candidat per a una API pública.

Tot el que hem vist fins ara comparteix una limitació: el client pregunta i el servidor respon. Com avisa la Botiga Aroma RàpidEnviaments que una comanda està pagada i a punt per recollir?

L'opció ingènua és el polling: que RàpidEnviaments ho consulti cada minut.

Amb una comanda cada mitja hora i una consulta per minut, el 98 % de les peticions són inútils: gasten recursos a totes dues bandes i tot i així l'avís arriba amb fins a un minut de retard.

Un webhook inverteix la direcció: el consumidor registra una URL seva, i el proveïdor li fa un POST quan passa alguna cosa. És, literalment, "una API a l'inrevés": ara la Botiga Aroma és el client HTTP i RàpidEnviaments el servidor.

L'enviament de l'esdeveniment:

Quatre decisions de disseny que veuràs en tots els webhooks seriosos i que convé interioritzar des d'ara:

1. Signatura criptogràfica (Aroma-Signatura): el receptor recalcula un HMAC del cos amb un secret compartit i verifica que coincideix. Sense això, qualsevol que conegui la URL pot inventar-se esdeveniments.
2. Identificador d'esdeveniment (Aroma-Esdeveniment-Id): permet al receptor detectar duplicats. Els webhooks garanteixen lliurament "com a mínim una vegada", així que el receptor ha de ser idempotent.
3. Reintents amb espera creixent: si el receptor no respon 2xx, l'emissor reintenta a intervals cada cop més grans durant hores, i avisa si acaba desistint.
4. Tipus d'esdeveniment amb espai de noms (comanda.pagada, comanda.enviada, ressenya.publicada): permet subscriure-s'hi selectivament i afegir esdeveniments nous sense trencar res.

Els webhooks no substitueixen l'API REST: la complementen. L'habitual és que l'esdeveniment contingui el just i que el receptor cridi després l'API per obtenir-ne el detall complet i actualitzat.

Completem el mapa amb tres mecanismes que apareixeran en la teva vida professional:

• Cues i streaming de missatges (RabbitMQ, Kafka, SQS): l'equivalent intern dels webhooks. L'emissor publica un esdeveniment en un intermediari i els interessats el consumeixen al seu ritme. Aporten persistència, reintents, ordre i desacoblament total. La Botiga Aroma els faria servir perquè els serveis de facturació, fidelització i analítica reaccionin a comanda.pagada sense que el servei de comandes sàpiga ni tan sols que existeixen.
• Server-Sent Events (SSE): un canal HTTP de llarga durada pel qual el servidor envia missatges al client. Unidireccional, senzill, sobre HTTP normal, amb reconnexió automàtica inclosa al navegador. Ideal per al panell intern de la Botiga Aroma mostrant les comandes que entren en directe.
• WebSockets: canal bidireccional persistent sobre una connexió promocionada des d'HTTP. Necessari quan tots dos extrems parlen contínuament: un xat d'atenció al client, per exemple.

Una regla útil: si l'usuari s'ha d'assabentar d'alguna cosa sense demanar-la, necessites un d'aquests quatre; cap API REST, GraphQL o gRPC unària no ho resol tota sola.

Preguntes concretes, en ordre d'importància:

1. Qui consumeix l'API? Si són tercers que no controles, REST. La barrera d'entrada més baixa guanya gairebé sempre; una API pública en gRPC seria un error.
2. Les dades són cacheables? Si el catàleg el consulten milers de vegades i canvia poc, la memòria cau HTTP gratuïta de REST és un argument de pes difícil d'igualar.
3. Els teus clients necessiten combinacions molt variables de dades? Si tens moltes pantalles diferents sobre el mateix model i pateixes de debò l'over/under-fetching, GraphQL hi aporta valor real.
4. És comunicació interna amb volum alt i latència crítica? gRPC. Controles tots dos extrems, així que l'acoblament del contracte no fa mal i el rendiment es nota.
5. L'emissor és el servidor? Webhooks cap a fora, cues cap a dins. No hi ha debat: HTTP client-servidor no cobreix aquest cas.
6. Quina és la mida i l'experiència del teu equip? Una arquitectura excel·lent que ningú no sap operar és pitjor que una de bona que tothom entén. GraphQL mal operat és una font inesgotable d'incidències de rendiment.

Tres advertiments, per experiència acumulada del sector:

• No adoptis GraphQL només per evitar dues peticions. Amb HTTP/2 diverses peticions petites surten barates, i REST admet paràmetres d'expansió i selecció de camps.
• No facis servir gRPC cap a l'exterior tret que els teus consumidors siguin equips tècnics amb capacitat per integrar-lo.
• No implementis webhooks sense signatura, reintents i idempotència. Un webhook mal fet genera comandes duplicades o esdeveniments perduts, i totes dues coses es veuen a la comptabilitat.

Amb tot el mapa sobre la taula, així queda la decisió de l'equip, i és la que seguirem durant la resta del curs:

I una decisió igual d'important: GraphQL, de moment, no. L'equip ho ha valorat i ha conclòs que les seves pantalles són poques i estables, que la memòria cau del catàleg és un actiu que no vol perdre i que l'equip és petit. És una decisió revisable, presa amb arguments i anotada. Això és dissenyar; el contrari és seguir la moda.

• Triar per moda i no per problema. Pregunta't sempre quina limitació concreta estàs patint avui. Si no la saps anomenar, no canviïs de tecnologia.
• Creure que GraphQL substitueix REST. Són complementaris. Moltes empreses exposen GraphQL per als seus propis clients i REST per a tercers, sobre el mateix backend.
• Oblidar que GraphQL perd la memòria cau HTTP. Si el teu trànsit és majoritàriament lectura de dades poc canviants, aquesta pèrdua pot costar més del que estalvies en peticions.
• Fer servir gRPC al navegador sense passarel·la. No funciona directament: necessites gRPC-Web i un servidor intermediari que tradueixi.
• Canviar els números de camp d'un .proto. Trenca la compatibilitat binària de manera silenciosa i difícil de diagnosticar. Els números són el contracte.
• Tractar un webhook com un lliurament garantit i únic. Arriba com a mínim una vegada, i de vegades més. Sense idempotència al receptor, tindràs duplicats.
• Posar dades completes i sensibles al cos del webhook. Envia el mínim i deixa que el receptor consulti l'API si necessita més: l'esdeveniment pot arribar tard i amb dades ja obsoletes.
• Consell: mantén una regla senzilla —REST cap a fora, gRPC cap a dins, esdeveniments per a allò asíncron— i desvia-te'n només amb una raó que puguis escriure en dues línies.

Per a cada necessitat de la Botiga Aroma, tria entre REST, GraphQL, gRPC, webhook o SSE, i justifica-ho amb dos arguments:

1. Un comparador de preus extern vol consultar el catàleg cada hora.
2. El servei de comandes comprova l'estoc 800 vegades per segon abans de confirmar compres.
3. La pantalla del "meu compte" d'Aroma Mòbil mostra dades del client, les seves tres últimes comandes, l'estat d'enviament de cadascuna i les seves ressenyes.
4. El proveïdor de torrefacció s'ha d'assabentar tan bon punt l'estoc d'un cafè baixa de 20 unitats.
5. El panell del magatzem mostra les comandes que van entrant, sense recarregar.

Dissenya el webhook comanda.enviada que la Botiga Aroma enviarà al client que ho sol·liciti. Especifica: el cos JSON de l'esdeveniment, les capçaleres necessàries, què ha de respondre el receptor, què farà l'emissor si no respon i quines mesures de seguretat hi inclous.

La pantalla de detall d'un cafè a Aroma Mòbil necessita: nom, preu, estoc, les cinc últimes ressenyes (autor i puntuació) i el nom del torrefactor.

1. Quantes peticions REST caldrien amb un disseny ingenu?
2. Escriu la consulta GraphQL equivalent.
3. Proposa dues solucions dins de REST que redueixin el nombre de peticions sense adoptar GraphQL.
4. Què s'hi perd en cada cas?

Solució 1

1. REST. És un tercer desconegut que s'ha d'integrar sense fricció, i el catàleg és contingut públic i cacheable: Cache-Control fa que moltes d'aquestes consultes ni tan sols arribin al servidor.
2. gRPC. És trànsit intern amb tots dos extrems sota control, on el format binari i HTTP/2 redueixen latència i CPU respecte a JSON; a més el contracte .proto evita errors de tipus en un camí crític.
3. GraphQL seria el candidat ideal per combinar quatre fonts de dades en una sola consulta, i evitar l'N+1 de peticions. Ara bé, si és l'única pantalla amb aquest problema, la resposta pragmàtica és un endpoint REST agregat (GET /v1/clients/cli_842/resum): resol el cas sense introduir tota una tecnologia.
4. Webhook. L'emissor és la Botiga Aroma i el receptor és una empresa externa; el sondeig constant seria un malbaratament i afegiria retard a l'avís.
5. SSE. És un flux unidireccional del servidor al navegador, funciona sobre HTTP normal i es reconnecta sol. Un WebSocket seria innecessàriament complex perquè el panell no envia res de tornada.

Solució 2

Cos de l'esdeveniment:

Capçaleres:

Què ha de respondre el receptor: un 2xx (idealment 200 OK o 204 No Content) com més aviat millor, abans de processar l'esdeveniment. La regla és acceptar, encuar i processar de manera asíncrona: si trigues a respondre perquè estàs fent feina pesant, l'emissor ho pot considerar una fallada i reintentar-ho, i generar duplicats.

Si no respon: reintents amb espera creixent (per exemple, als 30 s, 2 min, 10 min, 1 h, 6 h i 24 h), registre de cada intent accessible per al consumidor, avís per correu després de diverses fallades i desactivació de l'endpoint després d'un nombre de fallades consecutives.

Seguretat:

• Signatura HMAC-SHA256 del cos amb un secret compartit, que el receptor verifica abans de processar res.
• Marca temporal dins de la signatura per rebutjar reenviaments antics (atacs de repetició).
• HTTPS obligatori a la URL de destinació.
• Identificador d'esdeveniment per descartar duplicats al receptor.
• Dades mínimes: res de dades de pagament ni personals innecessàries; si en cal més, que consulti l'API autenticat.

Solució 3

1. Peticions REST amb disseny ingenu: tres.

2. Consulta GraphQL: una.

3. Dues solucions dins de REST:

• Paràmetre d'expansió: GET /v1/cafes/caf_001?incloure=ressenyes,torrefactor, que retorna els recursos relacionats incrustats a la mateixa resposta. Una sola petició, i continua sent un GET cacheable.
• Recurs agregat orientat a la pantalla: GET /v1/cafes/caf_001/detall, dissenyat específicament per a aquesta vista. Simple i molt eficient.

4. Què s'hi perd en cada cas:

• Amb GraphQL: la memòria cau HTTP (tot és POST a /graphql), els codis d'estat significatius i la possibilitat de provar la crida des del navegador; a més cal controlar el cost de les consultes.
• Amb el paràmetre d'expansió: la memòria cau es fragmenta (cada combinació d'incloure és una entrada diferent) i el servidor es complica; si se n'abusa, s'acaba reimplementant GraphQL a mà i pitjor.
• Amb el recurs agregat: s'acobla l'API a una pantalla concreta. Si cada vista nova hi afegeix el seu propi endpoint, l'API s'omple de recursos a mida difícils de mantenir i de documentar.

No hi ha cap opció gratuïta: totes tres són intercanvis conscients, i triar bé consisteix a saber quin fa menys mal en el teu context.

Ja tens el mapa complet d'estils d'integració. REST destaca per la seva simplicitat, la seva universalitat i la memòria cau que hereta d'HTTP, i és l'elecció natural quan el consumidor pot ser qualsevol. GraphQL resol l'over-fetching i l'under-fetching donant al client el control dels camps, a canvi de perdre la memòria cau HTTP i d'haver de governar el cost de les consultes. gRPC aporta contracte fort, format binari i streaming, i brilla entre serveis interns on controles tots dos extrems. I els webhooks, juntament amb les cues, SSE i WebSockets, cobreixen el buit que cap model petició-resposta no pot cobrir: que el servidor prengui la iniciativa. La conclusió pràctica és que no competeixen: la Botiga Aroma farà servir REST cap a fora, gRPC cap a dins i webhooks per a les seves integracions, i ha deixat GraphQL fora per raons escrites i revisables.

Amb això tanquem el mòdul 1. Saps què és una API i per a qui es dissenya, d'on ve l'ecosistema actual, com funciona HTTP per sota, en què consisteixen les sis restriccions de REST, com mesurar la maduresa d'una API i quines alternatives hi ha. Toca passar de comprendre a construir. Al mòdul 2, Disseny d'APIs RESTful, començarem a dissenyar l'API de la Botiga Aroma peça a peça: els seus principis de disseny, els seus recursos i URI, l'ús precís de cada mètode HTTP i de cada codi d'estat, la negociació de contingut, el filtratge i la paginació, el versionat i la documentació. És el moment en què les idees d'aquest mòdul es converteixen en decisions concretes sobre un contracte real.