Vam tancar el mòdul 1 dient que tocava passar de comprendre a construir. Abans d'escriure la primera línia de servidor, hi ha una etapa que massa gent s'estalvia i que és exactament on es guanyen o es perden els projectes d'API: el disseny del contracte. Aquesta lliçó és la lliçó paraigua del mòdul 2. Encara no entra en com s'anomenen les URIs ni en quin codi d'estat cal retornar —això són les lliçons següents—, sinó en el mètode de treball: com es decideix quina API cal construir, amb quins principis rectors i amb quins artefactes. Al final de la lliçó tindràs a la mà la guia d'estil de l'API de la Botiga Aroma, un document viu que les set lliçons següents aniran omplint i que el mòdul 3 implementarà al peu de la lletra.

1. API-first davant de code-first
2. El procés de disseny en set passos
3. Pas 1: identificar consumidors i casos d'ús
4. Pas 2: extreure els substantius del domini
5. Pas 3: decidir què es converteix en recurs i què no
6. Principis rectors del disseny
7. Granularitat: ni massa fina ni massa gruixuda
8. Dissenyar per al consumidor, no per a la base de dades
9. Tolerància a l'evolució i principi de robustesa
10. La guia d'estil de l'API de la Botiga Aroma
11. Mapa del mòdul 2

Hi ha dues maneres d'arribar a tenir una API, i no donen el mateix resultat.

En l'enfocament code-first s'escriu primer l'aplicació i l'API apareix després, gairebé com un subproducte: s'agafen els serveis que ja existeixen, se'ls penja una capa HTTP i es genera la documentació a partir del codi. És ràpid al principi i funciona raonablement bé quan l'únic consumidor és el teu propi frontend.

En l'enfocament API-first es fa el contrari: el contracte es dissenya, es revisa i s'acorda abans d'implementar res. L'especificació és l'artefacte principal; el codi n'és la realització. Els consumidors poden començar a treballar contra un simulacre (mock) generat des del contracte mentre l'equip de servidor l'implementa.

La Botiga Aroma té quatre consumidors diferents i un d'ells és una empresa externa. Redissenyar el contracte després que RàpidEnviaments hagi integrat els seus sistemes costa reunions, versions i diners. Per això el curs adopta API-first: el mòdul 2 sencer dissenya el contracte sobre el paper i el mòdul 3 l'implementa.

Un matís honest: API-first no vol dir "dissenyar-ho tot perfecte abans de tocar codi". Vol dir que el contracte va al davant i es revisa com es revisa el codi. Es pot iterar, però s'itera sobre el document, no sobre una API ja publicada.

Els passos 1 a 3 són aquesta lliçó. Els passos 4 i 5 són les lliçons 02-02 a 02-06. El pas 6 aterra a 02-07 i 02-08. El pas 7 es treballa a fons a 05-04. El cicle es tanca: allò que aprens validant amb consumidors torna al principi.

Una API no es dissenya "per al domini": es dissenya per a algú que la cridarà. El primer lliurable no és una llista d'endpoints, sinó una llista de consumidors amb les seves necessitats reals.

D'aquí surten els casos d'ús, escrits com a frases d'usuari, no com a endpoints:

• "Com a visitant vull veure els cafès disponibles filtrats per origen i torrefacció."
• "Com a client vull afegir dues bosses d'Etiòpia Yirgacheffe a la meva cistella i pagar-les."
• "Com a client vull consultar l'estat de la meva comanda i descarregar la factura."
• "Com a moderador vull aprovar o rebutjar una ressenya pendent."
• "Com a RàpidEnviaments vull assabentar-me que una comanda s'ha pagat sense haver de preguntar-ho cada minut."

Aquest darrer cas d'ús és el que va fer aparèixer els webhooks a 01-07: la llista de casos d'ús també decideix l'arquitectura, no només els endpoints.

Un detall important: els consumidors tenen necessitats diferents i de vegades enfrontades. Aroma Mòbil vol respostes petites perquè paga la xarxa; el panell intern vol respostes riques perquè pinta taules amb moltes columnes. Aquesta tensió no es resol creant dues APIs paral·leles, sinó amb mecanismes de contracte: selecció de camps i expansió, que es dissenyen a 02-05.

La tècnica és deliberadament simple: escriu en prosa què fa el negoci i subratlla els substantius.

"Un client navega pel catàleg de cafès, cadascun amb el seu origen, la seva torrefacció i les seves notes de tast. Afegeix línies a la seva cistella i confirma una comanda, que té un total i un estat. La comanda es paga i genera una factura. Quan es paga, RàpidEnviaments crea un enviament. Després, el client pot escriure una ressenya d'un cafè, que un moderador aprova o rebutja, i a la qual la botiga pot publicar una resposta."

Substantius candidats: client, catàleg, cafè, origen, torrefacció, notes de tast, línia, cistella, comanda, total, estat, pagament, factura, enviament, ressenya, resposta, moderador.

I els verbs, que anotem a part perquè són la font dels problemes més interessants: navegar, afegir, confirmar, pagar, generar, aprovar, rebutjar, respondre.

No tots els substantius mereixen una URI. Aplica aquests filtres:

1. Té identitat pròpia? El pots assenyalar i dir "aquest d'aquí"? Una comanda sí (com_5001); un total, no: és un atribut d'una comanda.
2. Algú necessita adreçar-lo per separat? Una ressenya sí: es modera d'una en una. Una torrefacció no: és un valor d'un enumerat.
3. Té cicle de vida propi? Un enviament neix, canvia d'estat i acaba. Una nota de tast no: viu i mor amb el seu cafè.
4. Es manipula independentment del seu pare? Una línia de cistella sí, perquè se'n canvia la quantitat sense tocar la resta.

Aplicat a la Botiga Aroma:

La columna de la dreta es justifica a 02-02, que és on s'expliquen les regles d'anomenament, la imbricació i els singleton. Aquí l'important és el criteri: recurs és allò que té identitat, cicle de vida i necessitat de ser adreçat.

Aquests sis principis són els que aplicarem, lliçó rere lliçó, cada vegada que calgui decidir alguna cosa.

Si /cafes accepta ?limit=20, aleshores /comandes accepta ?limit=20, encara que per a comandes haguessis preferit dir-li ?mida. Una API amb vint decisions bones però diferents entre si és pitjor que una API amb vint decisions acceptables i idèntiques: el consumidor n'aprèn la primera i dedueix les dinou restants.

Un desenvolupador que ja ha fet servir GET /v1/cafes/caf_001 hauria de poder escriure GET /v1/comandes/com_5001 sense obrir la documentació i encertar-la. Prova pràctica: ensenya tres endpoints a algú i demana-li que n'escrigui el quart. Si l'encerta, l'API és previsible.

L'API exposa coses sobre les quals s'opera amb els mètodes d'HTTP, no funcions remotes. POST /v1/comandes/com_5001/pagament en lloc de POST /v1/pagarComanda. Això ja ho vam justificar a 01-04 i 01-05; el cas difícil —les accions que no encaixen en CRUD— es resol a 02-02.

Si el GET d'un cafè retorna preuEuros i estoc, el POST que el crea hauria d'acceptar aquests mateixos noms de camp. Si POST /cafes retorna el recurs creat, PUT /cafes/{id} també hauria de retornar el recurs actualitzat. Les asimetries gratuïtes obliguen a memoritzar excepcions.

Tot allò que el consumidor pot observar forma part del contracte: noms de camp, tipus, codis d'estat, capçaleres, missatges d'error, ordre per defecte d'una col·lecció. El que no vulguis garantir, no ho exposis. I el que exposis, no ho canviïs sense versionar (02-07).

Un error és una resposta més i es dissenya igual de bé que un èxit. Ha de dir què ha fallat, per què i què pot fer el client. El format el fixa 02-04.

La granularitat és quanta feina fa una sola crida. És una de les decisions amb més conseqüències i no té resposta universal.

API massa fina. Cada recurs mínim té el seu endpoint i el client compon. Pintar la fitxa d'un cafè obliga a: demanar el cafè, demanar-ne les ressenyes, demanar el client de cada ressenya... És la chattiness (verbositat): moltes anades i vingudes. En una xarxa mòbil amb 150 ms de latència, vuit crides encadenades són més d'un segon perdut només en viatges.

API massa gruixuda. Un únic endpoint retorna el cafè amb les seves ressenyes, els clients de les ressenyes, l'estoc per magatzem i les recomanacions. Una sola crida, però: respostes enormes, gairebé tot sense fer servir (over-fetching), memòria cau inútil (qualsevol canvi ho invalida tot) i un contracte acoblat a una pantalla concreta que es trencarà quan la pantalla canviï.

La postura de la Botiga Aroma: una API de granularitat mitjana orientada a recursos, amb dues vàlvules d'escapament controlades que es dissenyen a 02-05 —expansió (expandir) per reduir crides i selecció de camps (camps) per reduir pes— i dades ja incrustades on l'ús real ho demana (el nom del cafè dins d'una línia de comanda, perquè el client no hagi de resoldre cada cafeId).

L'error més freqüent i més car: publicar les taules. S'agafa l'esquema relacional, es genera un endpoint per taula i a això se'n diu API REST.

Què passa quan exposem la taula cafes tal com és:

Problemes: el consumidor ha de traduir cod_torrefaccio: 1 a "clar" amb una taula que no té; fk_origen: 12 no li diu res; preu_centims l'obliga a conèixer una decisió d'emmagatzematge; esborrat_logic, usuari_alta i versio_fila són lampisteria interna que ara forma part del contracte i no es pot treure sense trencar clients. I si demà es normalitza la taula, l'API es trenca.

La representació dissenyada per al consumidor:

La regla és: la representació és una projecció pensada per a qui la llegeix, no un abocament de la fila. La base de dades pot continuar guardant cèntims, claus foranes i banderes d'esborrat; això és cosa de la capa de persistència (03-05).

El principi de robustesa de Jon Postel diu: "sigues conservador en allò que envies, liberal en allò que acceptes". Traduït a una API:

• Com a servidor: emet exactament allò que promet el contracte. Res de camps que apareixen de tant en tant ni de tipus que canvien.
• Com a client: no et trenquis perquè arribi un camp que no esperaves. Això és el tolerant reader, i és el que permet que el servidor afegeixi camps sense publicar una versió nova.

Conseqüències de disseny que adoptem ja:

• Els enumerats poden créixer. Si demà apareix torrefaccio: "molt_fosc", els clients l'han d'ignorar amb elegància, no petar. Es documenta des del primer dia.
• Els camps nous són opcionals i additius.
• Mai no es reutilitza un nom de camp amb un altre significat.
• Les col·leccions van embolcallades en un objecte ({"dades": [...], "total": n}) precisament per poder afegir metadades sense canviar el tipus de la resposta. S'argumenta a 02-05.

Què és exactament un canvi trencador i què no, i com es gestiona la depreciació, és la lliçó 02-07.

Aquest és l'artefacte central del mòdul. Una guia d'estil és un document curt, versionat al repositori, on s'escriuen les convencions que tota l'API respecta. Serveix per a tres coses: decidir ràpid, revisar en pull request i acollir gent nova.

Comencem amb les decisions ja preses (mòdul 1) i les que aquest mòdul anirà tancant:

Dos advertiments sobre les guies d'estil:

1. S'escriuen per complir-se. Una guia que ningú no revisa a les pull requests és decoració. A 05-05 veurem com automatitzar part de la comprovació (linters d'OpenAPI).
2. Les convencions són arbitràries, la consistència no. camelCase no és objectivament millor que snake_case; el que sí que és objectivament pitjor és fer servir totes dues.

En acabar el mòdul tindràs el contracte complet de l'API de la Botiga Aroma: les seves URIs, els seus mètodes, els seus codis, les seves representacions, les seves col·leccions paginades, la seva política de versions i la seva documentació. El mòdul 3 l'implementa amb Node.js i Express sense inventar-se res de nou.

• Començar pels endpoints. Si el teu primer full de disseny és una llista d'URLs, t'has saltat els consumidors i el domini. Comença per casos d'ús escrits en llenguatge de negoci.
• Dissenyar l'API mirant l'ORM. Els noms de columna, les claus foranes i les banderes internes no són contracte. Projecta, no aboquis.
• Dissenyar l'API mirant la pantalla. L'extrem oposat i també nociu: endpoints que només serveixen per a una vista concreta envelleixen amb aquesta vista. Dissenya recursos i dona al client eines (camps, expandir) per adaptar-los.
• Optimitzar abans de tenir el problema. No afegeixis expansió, filtres exòtics ni memòria cau de negoci "per si de cas". Cada mecanisme del contracte s'ha de documentar, provar i mantenir per sempre.
• Confondre consistència amb rigidesa. Hi haurà excepcions legítimes (la factura en PDF, per exemple). L'important és que siguin poques, conscients i escrites a la guia d'estil, no accidents.
• Consell: escriu primer la resposta. Abans de decidir la URL, escriu a mà el JSON que voldries rebre en el cas d'ús principal. Moltes decisions de disseny s'aclareixen soles en veure'l.
• Consell: la prova del desenvolupador nou. Si algú que no ha participat en el disseny necessita preguntar com es diu el paràmetre de paginació, l'API encara no és previsible.

La Botiga Aroma vol afegir subscripcions: un client rep una bossa de cafè cada mes, amb una periodicitat, un mètode de pagament, una adreça de lliurament i un historial de lliuraments ja fets. A més, cada subscripció es pot pausar.

Decideix, justificant-ho amb els quatre criteris de la secció 5, quins d'aquests substantius són recursos i quins atributs: subscripció, periodicitat, mètode de pagament, adreça de lliurament, lliurament, pausa.

La pantalla de "les meves comandes" d'Aroma Mòbil fa avui aquestes crides:

I la pantalla només mostra, per comanda: data, estat, total i el nom del primer cafè. Diagnostica el problema i proposa dues solucions de disseny diferents, indicant l'inconvenient de cadascuna.

Afegeix a la taula de la secció 10 tres files noves que avui no hi són i que saps que faran falta, per a aquests tres assumptes: (a) com s'anomenen les capçaleres pròpies de la Botiga Aroma, (b) quina zona horària es fa servir a les dates d'entrada que envia el client, (c) què passa amb els camps desconeguts que un client enviï al cos d'un POST. Redacta la convenció en una frase per fila.

Solució 1

Solució 2

Diagnòstic: API massa fina per a aquest cas d'ús. La pantalla necessita quatre dades per comanda i provoca de l'ordre de 38 crides. És chattiness pura, agreujada perquè Aroma Mòbil pateix latència de xarxa mòbil. A més hi ha over-fetching en l'altre sentit: de cada cafè es descarrega tot per llegir només nom.

Solució A — que la col·lecció retorni ja allò que es pinta. GET /v1/clients/cli_842/comandes retorna cada comanda amb dataCreacio, estat, totalEuros i les línies amb el nom del cafè ja incrustat. Una sola crida. Inconvenient: es duplica el nom del cafè en moltes respostes i cal mantenir aquesta còpia coherent; a més la resposta creix per a tots els consumidors, inclosos els que no necessiten les línies.

Solució B — expansió i selecció de camps. GET /v1/clients/cli_842/comandes?expandir=linies.cafe&camps=id,dataCreacio,estat,totalEuros,linies. Una crida, i cada consumidor demana el que necessita. Inconvenient: mecanismes que cal documentar, validar i provar; obren la porta a consultes cares i compliquen la memòria cau, perquè cada combinació de paràmetres és una URL diferent.

(La decisió de la Botiga Aroma combina les dues: incrusta el nom del cafè a les línies —dada estable i sempre necessària— i ofereix expandir/camps com a vàlvula. Es tanca a 02-05.)

Solució 3

Sobre l'última: és una decisió discutible i convé entendre-la. Rebutjar camps desconeguts (strict) detecta errades del client a l'instant; ignorar-los (tolerant) facilita que un client nou parli amb un servidor vell. La Botiga Aroma és estricta a l'entrada i tolerant a la sortida, que és exactament el principi de robustesa de la secció 9.

Dissenyar una API RESTful no comença dibuixant URLs: comença sabent qui la farà servir i per a què, extraient els substantius del domini i decidint amb criteri quins mereixen ser recursos. A partir d'aquí, un grapat de principis rectors —consistència, previsibilitat, orientació a recursos, simetria, contracte estable i errors útils— resolen la majoria de les decisions del dia a dia, mentre que la granularitat i el rebuig a exposar la base de dades eviten els dos errors estructurals més cars. Tot això es materialitza en un artefacte concret: la guia d'estil, que hem obert amb les decisions ja fermes de la Botiga Aroma i que anirem omplint a cada lliçó.

Amb el mètode clar i els consumidors identificats, toca la primera decisió concreta del contracte: quins recursos existeixen i com s'anomenen les seves URIs. A la lliçó següent, 02-02 Recursos i URIs, convertirem la llista de substantius en un mapa complet d'adreces —col·leccions, elements, subrecursos imbricats i singleton—, fixarem les regles d'anomenament, distingirem què va a la ruta i què a la query string, triarem el tipus d'identificador i resoldrem el problema que cap CRUD no resol sol: com es modelen accions com pagar una comanda o moderar una ressenya.