REST no és HTTP, però pràcticament totes les APIs REST del món viatgen sobre HTTP. Si no entens el protocol, acabaràs copiant exemples sense saber per què funcionen i depurant a cegues quan deixin de fer-ho. Aquesta lliçó obre HTTP en canal: veurem en cru com és una petició i una resposta, què implica que el protocol sigui sense estat, com es descompon una URL, quines capçaleres apareixen a gairebé totes les APIs, per què tot ha d'anar xifrat i què canvia entre HTTP/1.1, HTTP/2 i HTTP/3. Acabarem observant trànsit real contra l'API de la Botiga Aroma amb curl -v i amb les eines del navegador.

Aquesta és una lliçó de mapa i fonaments: presentarem els mètodes i els codis d'estat com a panoràmica, però el seu estudi detallat correspon a les lliçons 02-03 i 02-04.

1. Què és HTTP i quin paper té en una API
2. Anatomia d'una petició HTTP
3. Anatomia d'una resposta HTTP
4. El model petició-resposta i l'absència d'estat
5. La URL i les seves parts
6. Capçaleres habituals en APIs
7. Panoràmica de mètodes i codis d'estat
8. HTTPS i TLS: per què tota API va xifrada
9. HTTP/1.1, HTTP/2 i HTTP/3
10. Observar HTTP: curl -v i les DevTools

HTTP (HyperText Transfer Protocol) és un protocol de la capa d'aplicació que defineix com un client demana alguna cosa a un servidor i com aquest respon. El defineixen tres característiques:

• És textual en les seves versions clàssiques: es pot llegir amb els ulls, cosa que facilita enormement depurar.
• Segueix un model petició-resposta: per cada petició hi ha exactament una resposta.
• És sense estat: el servidor no recorda res de peticions anteriors.

Quan a la lliçó 01-01 vam escriure curl https://api.botigaaroma.example/v1/cafes, curl va construir un missatge HTTP, el va enviar per una connexió de xarxa i ens va mostrar només el cos de la resposta. Ara veurem aquest missatge complet.

Tota petició HTTP té tres parts: línia de petició, capçaleres i, opcionalment, cos. Així és una petició completa per crear una comanda a la Botiga Aroma:

Analitzem cada element:

Línia de petició (POST /v1/comandes HTTP/1.1). Té exactament tres peces separades per espais:

Capçaleres: parells Nom: valor, un per línia. Són metadades sobre la petició: descriuen el missatge, no formen part de la dada enviada. Host és obligatòria en HTTP/1.1 perquè un mateix servidor pot allotjar molts dominis i necessita saber a quin va dirigida.

Línia en blanc: separa les capçaleres del cos. És obligatòria, i és la marca que li diu al servidor "les capçaleres s'han acabat".

Cos (body): les dades que s'envien. Aquí, la comanda en JSON. Les peticions GET normalment no porten cos; les de creació o modificació sí.

Punt clau: la ruta va sense domini a la línia de petició. El domini viatja a la capçalera Host. En escriure https://api.botigaaroma.example/v1/comandes, el client descompon aquesta adreça en les dues parts automàticament.

La resposta té la mateixa estructura, canviant-ne la primera línia:

Línia d'estat (HTTP/1.1 201 Created):

Capçaleres de resposta: aquí Content-Type indica que el cos és JSON codificat en UTF-8, Content-Length diu quants bytes ocupa, Location assenyala on ha quedat el recurs acabat de crear (una convenció molt útil que reprendrem a 02-04) i Cache-Control: no-store prohibeix desar aquesta resposta a la memòria cau, cosa raonable en una comanda.

Cos: la representació del recurs creat. Fixa't que el servidor hi ha afegit informació que el client no va enviar: l'id, l'estat inicial i el totalEuros calculat. El client no calcula preus; això és lògica de negoci del servidor.

HTTP funciona per torns estrictes: el client pregunta, el servidor respon. El servidor mai no inicia la conversa (per a això hi ha els webhooks, els Server-Sent Events i els WebSockets, que veurem a 01-07).

La propietat més important per a nosaltres és que HTTP no té estat (stateless): cada petició és independent i el servidor no recorda res de les anteriors. Si envies aquestes dues peticions seguides:

el servidor no sap que la segona ve del mateix client que la primera, tret que l'hi diguis explícitament a la petició mateixa.

Conseqüència pràctica número u: cada petició ha de portar tota la informació necessària per ser atesa, inclosa la identitat de qui la fa. Per això la capçalera Authorization es repeteix en totes i cadascuna de les peticions autenticades, i no "s'inicia sessió una vegada".

Conseqüència pràctica número dos: com que cap petició no depèn d'una d'anterior, qualsevol servidor d'un grup pot atendre qualsevol petició. Això és el que permet posar deu servidors darrere d'un balancejador i escalar horitzontalment.

Compte amb una confusió freqüent: que el protocol no tingui estat no vol dir que no hi hagi dades persistents. La cistella de la Botiga Aroma es desa a la base de dades i és un recurs més (/v1/cistelles/cis_77); el que no existeix és una "sessió" viva a la memòria d'un servidor concret. La diferència entre estat d'aplicació i estat de sessió és central en REST i la reprenem a 01-04.

Una URL identifica de manera única un recurs a la xarxa. Analitzem-ne una de completa de la Botiga Aroma:

Detalls que convé interioritzar:

• La query string comença amb ? i encadena parells clau=valor separats per &. És el lloc natural per al que modula la consulta (filtrar, ordenar, paginar), no per identificar el recurs. Ho desenvoluparem a 02-06.
• El fragment no arriba mai al servidor. No el facis servir mai per transportar dades d'una API.
• Els valors han d'anar codificats (percent-encoding) si contenen caràcters especials: un espai és %20, una ç es codifica en diversos bytes. Per això a l'exemple escrivim origen=Etiopia sense accent, o bé origen=Eti%C3%B2pia.

Amb curl, convé posar la URL entre cometes perquè l'intèrpret d'ordres no interpreti l'& com a "executa en segon pla":

També hi veuràs el terme URI. A la pràctica de les APIs web, URI i URL es fan servir com a sinònims; formalment, URI és el concepte general d'identificador i URL és un identificador que a més indica com localitzar el recurs.

Hi ha desenes de capçaleres estàndard. Aquestes són les que apareixeran una vegada i una altra al curs:

Tres precisions importants:

• Content-Type i Accept no són el mateix. Content-Type descriu allò que envio; Accept descriu allò que vull rebre. Una petició POST sol portar les dues: "t'envio JSON i en vull JSON de tornada". Una GET només porta Accept, perquè no envia cos. Aquest mecanisme s'anomena negociació de contingut i és matèria de 02-05.
• Authorization amb esquema Bearer és el patró dominant avui: s'envia un token que el servidor valida. Tota la mecànica (JWT, OAuth 2.0) es veu a 03-06 i 04-03.
• Les capçaleres no distingeixen majúscules de minúscules al nom (content-type és igual que Content-Type), encara que per convenció s'escriuen amb inicial majúscula. En HTTP/2 i HTTP/3 viatgen sempre en minúscules.

També hi ha capçaleres personalitzades. La convenció moderna és no fer servir el prefix X- (desaconsellat des de l'RFC 6648) i triar noms específics com ara Aroma-Peticio-Id.

Aquí només dibuixem el mapa. L'estudi detallat de cada mètode és a la lliçó 02-03 i el de cada codi d'estat a la 02-04.

El mètode indica la intenció de la petició sobre el recurs:

Dues propietats que ja convé tenir al radar, perquè expliquen per què l'elecció del mètode importa:

• Segur (safe): no modifica res al servidor. GET i HEAD ho són. Per això un cercador pot rastrejar enllaços sense por.
• Idempotent: repetir la mateixa petició diverses vegades deixa el sistema igual que fer-ho una sola vegada. GET, PUT i DELETE ho són; POST no. D'aquí que reintentar un POST /v1/comandes després d'una fallada de xarxa pugui generar dues comandes, un problema real que abordarem.

El primer dígit determina la família, i amb això ja en saps l'essencial:

La distinció entre 4xx i 5xx és de les més útils que hi ha a l'hora de depurar: 4xx vol dir "arregla la petició", 5xx vol dir "el problema és meu". Un servidor que retorna 200 OK amb un cos {"error": "no trobat"} està mentint al protocol i trencant tot l'instrumental automàtic que s'assenta en el codi: memòries cau, reintents, monitoratge i alertes.

HTTPS és HTTP transportat dins d'una connexió xifrada amb TLS (Transport Layer Security, el successor de SSL). Aporta tres garanties:

1. Confidencialitat: ningú del camí no pot llegir-ne el contingut. Sense TLS, la capçalera Authorization amb el token viatja en text pla i qualsevol de la mateixa xarxa wifi la pot copiar.
2. Integritat: ningú no pot alterar els missatges sense que es detecti.
3. Autenticitat: el certificat del servidor demostra que parles amb api.botigaaroma.example i no amb un impostor.

A la pràctica això vol dir:

• Mai no publiquis una API per http://. Ni tan sols "només per a proves": les URL de proves acaben en producció.
• Redirigeix el trànsit http a https amb 301, però no hi confiïs com a seguretat: la primera petició ja ha viatjat en clar.
• Els tokens i les claus d'API només són segurs si el canal ho és.
• L'API interna també va xifrada. La xarxa interna no és un lloc de confiança; el model de confiança zero assumeix que un atacant ja és a dins.

Verificar el certificat d'una API amb curl:

Ampliarem tot això a la lliçó 04-02, dedicada a la seguretat.

El model conceptual (petició, resposta, mètodes, capçaleres, codis) és idèntic en les tres versions. El que canvia és com es transporten els missatges:

Què canvia a la pràctica per a qui dissenya una API:

• No et canvia el codi. Una API REST funciona igual en les tres versions; normalment és el servidor web o el gateway qui decideix la versió, i el client negocia la millor disponible.
• Sí que canvia el cost de fer moltes peticions. Amb HTTP/1.1, fer 30 crides per pintar una pantalla era caríssim, i això va empènyer a dissenyar respostes grans que ho retornen tot. Amb HTTP/2 diverses peticions petites són molt més assumibles. És un argument que apareixerà quan discutim GraphQL a 01-07.
• Capçaleres barates: amb compressió, repetir Authorization a cada petició pesa poc.
• HTTP/2 i HTTP/3 exigeixen TLS a la pràctica (tots els navegadors ho requereixen), cosa que reforça el punt anterior.
• gRPC s'assenta en HTTP/2 precisament pel multiplexatge i l'streaming bidireccional.

No es pot aprendre HTTP sense veure'l. Amb dues eines n'hi ha prou per al 95 % dels casos.

L'opció -v (verbose) mostra la conversa completa. Les línies que comencen per > són el que envia el client; les que comencen per <, el que retorna el servidor; les que comencen per * són informació de la connexió.

Sortida (abreujada i comentada):

Què ens ensenya aquesta sortida:

• curl hi va afegir automàticament Host, User-Agent i Accept: */* ("accepto qualsevol format").
• La connexió va negociar HTTP/2 i TLS 1.3, i les capçaleres de resposta arriben en minúscules, com correspon a HTTP/2.
• El servidor permet posar-ho a la memòria cau 5 minuts (max-age=300) i envia un ETag, una empremta del contingut que permet revalidar sense tornar-lo a descarregar (lliçó 04-06).

Opcions de curl que farem servir durant tot el curs:

Un detall útil: en fer servir -d, curl ja assumeix POST i Content-Type: application/x-www-form-urlencoded, per la qual cosa la capçalera Content-Type: application/json és obligatòria si envies JSON. Oblidar-la és una de les causes més freqüents de rebre un 400 desconcertant.

Prem F12 al navegador i obre la pestanya Xarxa (Network). Amb ella pots:

1. Filtrar per Fetch/XHR per veure només les crides a APIs que fa la pàgina, i ignorar imatges i estils.
2. Clicar una petició i revisar-ne les pestanyes: Headers (línia de petició, codi d'estat i totes les capçaleres), Payload (el cos enviat), Response (el cos rebut) i Timing (on se n'ha anat el temps).
3. Fer servir Copia com a cURL al menú contextual: converteix qualsevol petició del navegador en una ordre curl reproduïble al terminal. És la tècnica més ràpida per depurar una crida que falla al web de la Botiga Aroma.

Un exercici molt formatiu: obre qualsevol botiga en línia real, filtra per Fetch/XHR i observa les crides que fa en afegir alguna cosa a la cistella. Hi veuràs en directe mètodes, rutes, codis d'estat i cossos JSON.

• Enviar JSON sense Content-Type: application/json. El servidor no endevina el format; el tractarà com a text o com a formulari i fallarà en interpretar-lo.
• Confondre Accept amb Content-Type. Regla mnemotècnica: Content-Type descriu el que va dins d'aquest sobre; Accept descriu el que vull de tornada.
• Posar dades sensibles a la query string. Les URL queden registrades als logs del servidor, als servidors intermediaris i a l'historial. Els tokens i les contrasenyes van a capçaleres o al cos, mai a la URL.
• Oblidar posar la URL entre cometes a curl quan porta &. L'intèrpret la parteix i reps resultats incoherents.
• Suposar que el servidor "recorda" la petició anterior. Sense estat vol dir exactament això: cada petició ha de ser autosuficient.
• Retornar 200 OK per als errors. Trenca memòries cau, reintents automàtics i monitoratge.
• Preocupar-se per HTTP/2 o HTTP/3 al codi de l'API. És una decisió d'infraestructura; la teva feina és dissenyar bé el contracte.
• Consell: dedica quinze minuts a llançar curl -v contra tres o quatre APIs públiques que facis servir. Veure capçaleres reals de serveis reals ensenya més que qualsevol taula.

Donada aquesta petició, respon: (a) quin mètode i ruta fa servir?; (b) a quin domini va dirigida?; (c) quin format envia i quin espera rebre?; (d) porta credencials?; (e) què està fent exactament?

Descompon aquesta URL en les seves sis parts i indica quina d'elles no arriba al servidor. Explica també si ?torrefaccio=clar&limit=10 identifica un recurs diferent o modula una consulta.

Escriu les ordres curl per:

1. Obtenir el cafè caf_001 mostrant les capçaleres de resposta.
2. Comprovar si existeix el recurs /v1/cafes/caf_999 sense descarregar-ne el cos.
3. Crear una ressenya amb POST /v1/ressenyes enviant {"cafeId":"caf_001","puntuacio":5,"comentari":"Excel·lent"} autenticat amb el token TOKEN123.
4. Demanar els cafès d'Etiòpia amb torrefacció clara, amb la URL correctament entre cometes.

Solució 1

• (a) Mètode PATCH sobre la ruta /v1/cafes/caf_002.
• (b) A api.botigaaroma.example, indicat a la capçalera Host (la línia de petició no porta mai el domini).
• (c) Envia application/json (Content-Type) i espera rebre application/json (Accept).
• (d) Sí: Authorization: Bearer ... amb un token.
• (e) Modifica parcialment el cafè caf_002, i en canvia només el preu a 13,50 €. Com que és PATCH i no PUT, la resta de camps (nom, origen, estoc) es conserven. És una operació típica del panell intern, i per això requereix autenticació.

Solució 2

La part que no arriba al servidor és el fragment #resultats: el navegador el fa servir localment i no l'envia mai.

La query string modula la consulta: el recurs continua sent la col·lecció de cafès (/v1/cafes), però en demanem un subconjunt filtrat i limitat. No és un recurs diferent; és la mateixa col·lecció vista amb altres criteris. Per això els filtres van a la query string i no a la ruta.

Solució 3

Errors freqüents en aquest exercici: oblidar Content-Type al punt 3 (el servidor no interpretaria el JSON), fer servir -X GET amb -I (són incompatibles: -I ja implica HEAD) i no posar entre cometes la URL del punt 4.

HTTP és el terreny sobre el qual es construeix tota la resta. Ja saps llegir una petició i una resposta en cru, distingir-ne les tres parts, descompondre una URL i reconèixer les capçaleres que apareixeran a cada lliçó del curs. Has vist que l'absència d'estat obliga que cada petició sigui autosuficient —i alhora és el que permet escalar—, que les famílies de codis separen clarament la culpa entre client i servidor, que HTTPS no és opcional i que les versions del protocol canvien el transport però no el model. I, sobretot, ja tens dues eines, curl -v i les DevTools, per observar el que passa de debò en comptes de suposar-ho.

Amb aquest material podem abordar la pregunta central del mòdul. A la lliçó següent, Principis bàsics de REST, veurem com Roy Fielding va convertir les propietats del web en sis restriccions arquitectòniques, què són exactament un recurs, un identificador i una representació, i per què moltes APIs que s'anuncien com a REST no ho són del tot.