Cada vegada que consultes el saldo del banc des del mòbil, pagues amb targeta en una botiga en línia o entres en un servei amb el teu compte de Google, hi ha una API treballant per sota. Les APIs són el teixit connectiu del programari modern: la manera estàndard com un programa demana alguna cosa a un altre programa sense necessitat de saber com està fet per dins. Aquesta primera lliçó defineix què és exactament una API, quin problema resol, quins tipus n'hi ha i per què se'n diu "contracte". També presenta la Botiga Aroma, la botiga de cafè d'especialitat que ens acompanyarà durant tot el curs, i tanca amb un primer exemple real de petició i resposta que anirem desgranant a les lliçons següents.

1. La idea central: interfícies que amaguen complexitat
2. El problema que resol una API
3. L'API com a contracte entre proveïdor i consumidor
4. Exemples quotidians: passarel·les de pagament, mapes i login social
5. Tipus d'API segons el seu àmbit
6. Què és una API web i el model client-servidor
7. Qui consumeix una API
8. APIs públiques, de socis i internes
9. L'escenari del curs: Botiga Aroma
10. Primer exemple end-to-end: GET /v1/cafes

API són les sigles d'Application Programming Interface, en català "interfície de programació d'aplicacions". Descomponguem el terme:

• Interfície: un punt de contacte definit entre dues parts. Un endoll és la interfície entre un electrodomèstic i la xarxa elèctrica.
• De programació: aquesta interfície no la fa servir una persona amb un ratolí, la fa servir un altre programa escrivint codi.
• D'aplicacions: les dues parts són peces de programari.

Una API és, doncs, el conjunt d'operacions que un programari ofereix a un altre programari, descrites de manera que es puguin invocar des de codi. L'essencial és allò que l'API no mostra: qui la fa servir no sap (ni li cal saber) en quin llenguatge està escrita, quina base de dades hi ha al darrere ni quants servidors l'atenen.

Pensa en la interfície d'un cotxe: volant, pedals i palanca. Això és l'"API" del cotxe. Pots conduir un cotxe de gasolina i un d'elèctric amb la mateixa interfície, encara que per dins siguin radicalment diferents. Si demà el fabricant canvia el motor, continues sabent conduir. Aquest desacoblament entre allò que s'ofereix i com està implementat és el cor de la idea.

Imagina que la Botiga Aroma vol mostrar el seu catàleg de cafès en tres llocs: el web d'escriptori, una aplicació mòbil i una pantalla tàctil de la botiga física. Sense API, cadascun d'aquests tres programes hauria de:

1. Connectar-se directament a la base de dades.
2. Conèixer els noms de les taules i les columnes.
3. Repetir les regles de negoci (un cafè sense estoc es mostra o no?, com es calcula el preu amb IVA?).

Les conseqüències són previsibles: regles duplicades que es desincronitzen, credencials de base de dades escampades per tot arreu i la impossibilitat de canviar l'esquema sense trencar tres aplicacions alhora.

Amb una API, aquesta lògica viu en un sol lloc i els tres clients demanen el mateix: "dona'm els cafès disponibles". Els problemes concrets que resol són:

La metàfora més útil per entendre una API és la de contracte. Hi ha dues parts:

• El proveïdor (o productor): qui publica i manté l'API. En el nostre cas, l'equip de backend de la Botiga Aroma.
• El consumidor (o client): qui la invoca. L'app mòbil, el web, un soci extern.

El contracte especifica, com a mínim:

• Quines operacions existeixen i com s'invoquen (adreces, verbs, paràmetres).
• Quines dades cal enviar i amb quin format i restriccions.
• Què es retorna en cas d'èxit: estructura, tipus, unitats.
• Què passa quan alguna cosa falla: com se senyala un error i quina informació es dona.
• Quines garanties hi ha: disponibilitat, límits d'ús, política de canvis.

I com tot contracte, té una conseqüència incòmoda: un cop publicat, no el pots trencar unilateralment. Si la Botiga Aroma canvia avui el nom del camp preuEuros per preu, l'app mòbil de milers d'usuaris deixarà de mostrar preus aquesta mateixa tarda. Aquesta idea —que una API és una promesa a llarg termini— explica bona part de les decisions de disseny que veurem al mòdul 2, i és la raó de ser del versionat (lliçó 02-07).

Consell primerenc: dissenya pensant que el contracte durarà anys i que no controles qui el consumeix. És un canvi de mentalitat respecte a escriure codi intern que pots refactoritzar quan vulguis.

Les APIs són més fàcils d'entendre amb casos que ja has fet servir com a usuari:

• Passarel·la de pagament: la Botiga Aroma no desa números de targeta ni parla amb els bancs. Envia a l'API de la passarel·la l'import i una referència de la comanda, i en rep una confirmació. La complexitat brutal del sistema de pagaments queda darrere d'una operació d'un parell de camps. A més, evita responsabilitats regulatòries enormes.
• Mapes: per mostrar on és la cafeteria física, el web demana a una API de mapes un mapa centrat en unes coordenades. Ningú de la Botiga Aroma no dibuixa carrers.
• Login social ("Entra amb Google"): la botiga no gestiona contrasenyes; delega l'autenticació en un proveïdor d'identitat i en rep la confirmació de qui és l'usuari. Veurem el mecanisme real (OAuth 2.0 i OpenID Connect) a la lliçó 04-03.
• Enviaments: quan una comanda es marca com a pagada, la Botiga Aroma crida l'API de la seva empresa de missatgeria, RàpidEnviaments, per generar l'etiqueta i obtenir un número de seguiment.

El patró es repeteix: no construeixis allò que pots consumir; no exposis per dins allò que pots oferir per fora.

No totes les APIs viatgen per la xarxa. Convé distingir tres àmbits, perquè el terme es fa servir per als tres:

Un exemple d'API de biblioteca que ja coneixes:

Les tres comparteixen filosofia, però les APIs web tenen una diferència crucial: la crida travessa la xarxa. Això introdueix latència, fallades de connexió, seguretat, control d'accés i versions que conviuen. Aquest curs tracta exclusivament d'APIs web i, dins d'aquestes, de l'estil REST.

Una API web és una API a la qual s'accedeix mitjançant el protocol HTTP a través d'una adreça de xarxa. Funciona sota el model client-servidor:

• El client pren la iniciativa: envia una petició.
• El servidor escolta, processa i retorna una resposta.
• La conversa sempre la comença el client (els webhooks, a 01-07, inverteixen aquesta direcció).

Fixa't en dos detalls importants del diagrama:

1. El client mai no parla amb la base de dades. Només coneix l'adreça de l'API.
2. Allò que retorna l'API no són "files d'una taula", sinó una representació en JSON pensada per ser consumida. Aquesta distinció entre la dada interna i la seva representació és central en REST i la desenvoluparem a la lliçó 01-04.

Saber qui hi ha a l'altre costat canvia el disseny. Els consumidors típics de l'API de la Botiga Aroma:

• Aplicació web d'una sola pàgina (SPA): la botiga en línia. S'executa al navegador i demana dades per JavaScript. És sensible al nombre de peticions i a les polítiques de seguretat del navegador (CORS, lliçó 04-05).
• Aplicació mòbil nativa: Aroma Mòbil, per a iOS i Android. Peculiaritat crítica: l'usuari decideix quan actualitza, així que versions antigues continuaran cridant la teva API durant mesos.
• Un altre servei del backend: el servei de facturació pregunta a l'API per les comandes del mes. És trànsit intern, amb requisits de rendiment diferents.
• Integracions de tercers: RàpidEnviaments consulta les comandes pendents de recollida; una eina de comptabilitat exporta les vendes.
• Eines i scripts: curl, Postman (lliçó 05-01), scripts de manteniment del mateix equip.

Segons a qui s'obri la porta, es distingeixen tres categories. És una decisió de negoci amb implicacions tècniques enormes:

Un error freqüent és tractar l'API interna com si no necessités disciplina. Quan l'empresa creix, l'API interna acaba tenint deu consumidors que no controles en el dia a dia, i la manca de contracte es paga cara.

A partir d'aquí, tot el que aprenguem s'aplicarà sobre un cas únic, perquè els conceptes no quedin en abstracte.

La Botiga Aroma és una botiga en línia de cafè d'especialitat. Ven cafès d'origen, torrefaccions pròpies i subscripcions mensuals. La seva realitat tècnica és:

• Una botiga web feta com a SPA.
• Una app mòbil, Aroma Mòbil, amb la qual els clients repeteixen comandes.
• Un panell intern d'administració que fa servir l'equip de magatzem i d'atenció al client.
• Una integració amb RàpidEnviaments, l'empresa de missatgeria que reparteix les comandes.

Els seus recursos (les "coses" que gestiona el negoci) són cinc, i seran els mateixos durant tot el curs:

L'API viu a https://api.botigaaroma.example/v1 i en realitat són dues APIs amb el mateix domini de negoci: una de pública (catàleg i ressenyes, perquè blogs i comparadors puguin mostrar-ne els cafès) i una d'interna (comandes, estoc, clients) que fan servir el panell d'administració i RàpidEnviaments com a soci.

A partir del mòdul 3 la implementarem amb Node.js 20 i Express, escrivint els identificadors en català (obtenirCafes, crearComanda, preuEuros) perquè el codi sigui fàcil de llegir.

Vegem l'API més simple possible en acció: demanar el catàleg. Farem servir curl, una eina de línia d'ordres que envia peticions HTTP i mostra la resposta. Està disponible a Linux, macOS i Windows 10 o superior.

Aquesta línia conté tres coses: el programa (curl), i una adreça que alhora indica on és l'API (api.botigaaroma.example), que hi parlem per canal xifrat (https) i què demanem (/v1/cafes, la llista de cafès de la versió 1 de l'API). Com que no hi indiquem res més, curl fa servir el mètode GET, que vol dir "dona'm això sense modificar res".

La resposta que retorna el servidor:

Analitzem la resposta peça a peça, sense entrar encara en el detall del protocol:

• És en JSON (JavaScript Object Notation), el format d'intercanvi dominant avui. Les {} delimiten objectes amb parells clau: valor, i els [] delimiten llistes.
• La clau dades conté la llista de cafès. Embolcallar la llista dins d'un objecte (en comptes de retornar l'array directament) deixa espai per afegir metadades com ara total sense trencar el contracte.
• Cada cafè té un id estable (caf_001). Aquest identificador és el que permet demanar després un cafè concret: GET /v1/cafes/caf_001.
• preuEuros deixa explícita la unitat al nom del camp. Un camp anomenat només preu obliga a llegir la documentació per saber si són euros o cèntims: una font clàssica d'errors.
• torrefaccio fa servir un valor d'un conjunt tancat i conegut (clar, mitja, fosc).

Si en comptes de la llista volem un cafè concret, canviem l'adreça:

Fixa't en un detall gens casual: l'adreça del recurs individual és la de la col·lecció més el seu identificador. Aquesta regularitat, que ara sembla anecdòtica, és un dels senyals d'identitat de REST i la formalitzarem a la lliçó 01-04.

Tot el que passa per sota (capçaleres, codis d'estat, mètodes) ho veurem a la lliçó 01-03, dedicada a HTTP. De moment queda't amb la imatge completa: un client demana alguna cosa a una adreça i un servidor respon amb una representació en JSON.

• Confondre l'API amb la base de dades. L'API no és una finestra a les taules: és una interfície de negoci. Exposar l'esquema intern tal qual et lliga per sempre a aquest esquema.
• Confondre l'API amb l'aplicació web. El web és un consumidor. Si dissenyes l'API pensant només en la pantalla que estàs construint avui, l'app mòbil que arribi demà no hi encaixarà.
• Creure que "API" sempre vol dir "API web". En una oferta de feina o en una conversa, convé precisar de quin àmbit es parla (biblioteca, sistema operatiu o xarxa).
• Oblidar que el contracte és una promesa. Abans de publicar un nom de camp, pensa si el voldràs mantenir d'aquí a dos anys.
• No anomenar les unitats. preuEuros, pesGrams o duracioSegons estalvien incidències reals en producció.
• Consell: quan comencis a dissenyar, escriu primer un exemple de petició i de resposta JSON, com el d'aquesta lliçó, abans d'escriure ni una sola línia de servidor. És l'essència de l'enfocament API-first que veurem a 01-02 i 05-02.

La Botiga Aroma vol que un blog de cafès extern mostri al seu web els tres cafès més venuts. Enumera com a mínim cinc elements que hauria d'especificar el contracte d'aquesta API perquè el blog s'hi pugui integrar sense preguntar res per correu electrònic.

Per a cada situació, indica qui és el consumidor i si l'API implicada hauria de ser pública, de socis o interna, justificant-ho breument:

1. El panell d'administració marca una comanda com a enviada.
2. Un comparador de preus mostra el catàleg de la Botiga Aroma.
3. RàpidEnviaments consulta cada 10 minuts les comandes pendents de recollir.
4. Aroma Mòbil mostra l'historial de comandes de l'usuari que ha iniciat sessió.

Dissenya el JSON que retornaria GET /v1/cafes/caf_002/ressenyes (les ressenyes d'un cafè). Ha d'incloure com a mínim dues ressenyes, amb identificador, autor, puntuació d'1 a 5, comentari i data. Aplica-hi el que has après sobre noms de camp, unitats i embolcall de la llista.

Solució 1

Un contracte mínim utilitzable hauria d'especificar:

1. L'adreça exacta de l'operació, per exemple GET https://api.botigaaroma.example/v1/cafes?ordenar=mesVenuts&limit=3.
2. Com s'autentica el blog: si necessita clau d'API i com s'envia.
3. L'estructura de la resposta: quins camps arriben, de quin tipus i quins poden faltar (nom text, preuEuros nombre decimal, estoc enter).
4. El comportament davant d'errors: què es retorna si la clau no és vàlida o el servei no està disponible, i com distingir-ho d'una resposta correcta buida.
5. Els límits d'ús: quantes peticions per minut s'admeten i què passa quan se superen.

Elements addicionals igualment vàlids: política de versionat i avís de canvis, condicions d'ús de les dades i de les imatges, i contacte de suport.

Solució 2

1. Panell d'administració → API interna. Modifica l'estat del negoci i només la fa servir personal de l'empresa.
2. Comparador de preus → API pública. Només llegeix catàleg, informació no sensible; comercialment interessa que es difongui.
3. RàpidEnviaments → API de socis. És una empresa externa concreta amb acord previ, amb credencials pròpies i accés limitat a les comandes que li pertoquen.
4. Aroma Mòbil → API interna (encara que sigui accessible des d'internet). És un client propi que accedeix a dades personals; requereix autenticació de l'usuari i retornar-li únicament les seves comandes.

Fixa't en el matís del cas 4: "interna" es refereix a qui la controla i per a qui es dissenya, no a si s'hi pot arribar des de la xarxa.

Solució 3

Decisions a destacar: la llista va embolcallada dins de dades per poder afegir-hi metadades; cada ressenya porta cafeId perquè sigui autoexplicativa encara que es copiï fora de context; puntuacio és un nombre enter i no un text; i la data fa servir el format ISO AAAA-MM-DD, que és inequívoc internacionalment (davant de 14/07/2026, que un consumidor nord-americà podria llegir malament).

Una API és una interfície que permet a un programa fer servir els serveis d'un altre sense conèixer-ne l'interior, i el seu valor rau tant en allò que exposa com en allò que amaga. Hem vist que funciona com un contracte entre proveïdor i consumidor, que hi ha APIs de biblioteca, de sistema operatiu i web, i que aquestes últimes segueixen el model client-servidor sobre HTTP. També hem classificat les APIs en públiques, de socis i internes, i hem conegut la Botiga Aroma, els cinc recursos de la qual —cafès, clients, comandes, ressenyes i cistelles— ens serviran de laboratori fins al final del curs. El primer GET /v1/cafes ja ens ha mostrat el patró fonamental: petició a una adreça, resposta en JSON.

Abans d'entrar en com es dissenyen aquestes interfícies, convé entendre d'on vénen. A la lliçó següent, Història i evolució de les APIs, recorrerem el camí que va de les crides a procediment remot fins a l'economia de les APIs actual, per comprendre per què REST es va imposar i quines lliçons pràctiques deixa aquesta història a qui dissenya una API avui.