La lliçó anterior va resoldre mitja promesa: Nómada Tasques ja sobreviu a F5. Però la Marta, l'Iván i la Lucía continuen tenint cadascun el seu propi localStorage, amb la seva pròpia versió del tauler, sense manera de veure's. L'altra meitat —que el tauler sigui el mateix per a tot l'equip— exigeix que les dades visquin en un servidor i que el navegador sàpiga parlar-hi sense recarregar la pàgina. Això és AJAX, i l'eina moderna per fer-ho és fetch. En aquesta lliçó aprendràs què va canviar AJAX al web, repassaràs l'HTTP que necessites de debò (verbs, codis i capçaleres), dominaràs fetch i l'objecte Response amb el seu parany més famós —un 404 no rebutja la promesa—, enviaràs dades en JSON i en FormData, construiràs URLs amb paràmetres, entendràs CORS prou per no perdre una tarda, i escriuràs js/dades/api-tasques.js, el germà de xarxa del repositori local. I per fi retiraràs aquelles llegirBacklogSimulat() i desarInformeSimulat() de 05-06 que fingien latència amb setTimeout.

1. Què és AJAX i què va canviar
2. XMLHttpRequest, l'avantpassat
3. HTTP en deu minuts: verbs, rutes, codis i capçaleres
4. fetch: la petició mínima
5. L'objecte Response i els mètodes de cos
6. El parany fonamental: fetch no rebutja amb 404 ni 500
7. Enviar dades: method, headers i body
8. Enviar FormData i fitxers
9. Paràmetres de consulta amb URL i URLSearchParams
10. CORS: per què el navegador et bloqueja
11. Autenticació: Authorization i credentials
12. Nómada Tasques: js/dades/api-tasques.js
13. Practicar de debò: json-server a la teva màquina
14. Errors Habituals i Consells
15. Exercicis
16. Conclusió

AJAX són les sigles d'Asynchronous JavaScript And XML, un nom encunyat el 2005 que avui és mitja mentida: gairebé ningú fa servir XML —es fa servir JSON— i la tècnica s'aplica a molt més que XML. El que la sigla anomena continua vigent: demanar dades al servidor des de JavaScript, sense recarregar la pàgina, i actualitzar només la part del DOM que canvia.

Compara els dos models:

El que AJAX fa possible, en termes de Nómada Tasques: la Marta prem el botó d'avançar estat, la targeta es mou de columna, i ni el scroll ni el filtre per responsable ni el focus es perden. El cicle estat → render → esdeveniment → estat nou → render que vas muntar a 06-06 continua manant; l'únic que canvia és que ara una part de l'«estat nou» arriba del servidor.

I hi ha una cosa que no canvia i convé dir aviat: el servidor continua manant. Una petició AJAX no és més segura que un formulari; l'usuari pot fabricar la que vulgui des de la consola. Tota validació del client és una cortesia; la de debò és al servidor.

Abans de fetch hi havia XMLHttpRequest (XHR), disponible des de principis dels 2000. El veuràs en codi antic i val la pena reconèixer-lo:

És l'estil de callbacks de 05-05 portat a l'extrem: res de promeses, res d'async/await, i el famós readyState amb els seus cinc valors numèrics. La comparació:

Avui es fa servir fetch llevat de dos casos: quan necessites una barra de progrés de pujada d'un fitxer gran, o quan mantens codi antic. Els dos buits de fetch —timeout i cancel·lació— es cobreixen amb AbortController, i aquesta és la lliçó següent.

Una petició HTTP té quatre parts: un verb, una ruta, unes capçaleres i de vegades un cos. La resposta té un codi d'estat, les seves pròpies capçaleres i el seu cos.

Idempotent significa que repetir la mateixa petició deixa el sistema igual que fer-la una vegada. PUT de la tasca 6 amb les mateixes dades, mil vegades, deixa una tasca 6 amb aquelles dades. POST mil vegades crea mil tasques. Aquella distinció sembla teòrica fins que a 07-03 decideixis quines peticions es poden reintentar sense por.

Una API REST anomena coses, no accions, i deixa que el verb digui què fer-hi:

Un antipatró habitual és POST /v1/crearTasca o GET /v1/esborrarTasca?id=6. El segon és especialment dolent: un GET no ha de canviar res, i qualsevol cercador o precarregador del navegador el podria disparar.

El domini https://api.tallernomada.example/v1 que farem servir en tota la lliçó és fictici. El TLD .example està reservat per l'IANA precisament per a documentació i no resoldrà mai. A l'apartat 13 muntaràs un servidor real a la teva màquina per practicar.

S'agrupen en famílies, i amb saber les famílies en vas sobrat:

La frontera entre 4xx i 5xx és la que governa la teva gestió d'errors: un 4xx l'arregla el client (corregeix les dades, inicia sessió, deixa d'insistir); un 5xx no l'arregla el client (reintenta més tard i avisa). Dues parelles que es confonen sovint:

• 401 Unauthorized significa «no sé qui ets» (falta o ha caducat la credencial). 403 Forbidden significa «sé qui ets i no pots». El primer demana iniciar sessió; el segon, no.
• 204 No Content és un èxit sense cos. Cridar .json() sobre ell llança, perquè no hi ha res per analitzar. Ho tindràs en compte a esborrarTasca().

L'error de novell més freqüent amb capçaleres: enviar un body amb JSON sense Content-Type: application/json. Molts servidors ho interpreten com a text pla i retornen un 400 desconcertant.

fetch(url, opcions) retorna una promesa que es resol amb un objecte Response així que arriben les capçaleres de la resposta. Amb el que saps de 05-06, es llegeix sense esforç:

Dos await, i cadascun espera una cosa diferent. Això és el que més costa al principi:

La primera promesa es resol amb les capçaleres; el cos pot continuar arribant. Per això resposta.json() és una altra operació asíncrona i necessita el seu propi await. Oblidar-ho produeix l'error més comú de tots:

Response descriu la resposta completa:

I els mètodes de cos, tots asíncrons perquè tots retornen promeses:

Els noms de capçalera no distingeixen majúscules: headers.get('Content-Type') i headers.get('content-type') són el mateix.

Una regla que sorprèn: el cos només es pot llegir una vegada. És un flux, i un cop consumit, s'ha acabat.

Si necessites llegir-lo dues vegades —per exemple, intentar json() i, si falla, mirar el text() per depurar—, clona abans:

Aquell patró et salvarà el dia que un proxy retorni una pàgina HTML d'error on esperaves JSON.

Aquesta és la cosa que cal saber de fetch, i la que més codi trencat ha produït:

La promesa de fetch només es rebutja si la petició no va arribar a completar-se: xarxa caiguda, DNS que no resol, CORS bloquejat, petició cancel·lada. Si el servidor respon —encara que respongui 404, 403 o 500— la promesa es resol amb normalitat.

El catch no s'executa. resposta.json() analitza el cos de l'error sense queixar-se, i la teva aplicació continua endavant amb escombraries. La correcció és sempre comprovar ok:

La taula que explica el perquè del disseny:

La lògica del disseny és defensable: fetch promet fer la petició HTTP, i un 404 és una petició HTTP feta amb èxit la resposta de la qual és «no existeix». Que sigui defensable no treu que sigui la primera causa de bugs de xarxa. A l'apartat 12 encapsularem la comprovació una sola vegada per no tornar a oblidar-la.

Fixa't a més en el detall de l'última fila del diagnòstic: quan CORS bloqueja una petició, JavaScript rep un TypeError genèric sense detalls. El motiu real només apareix a la consola del navegador. És intencionat —donar detalls seria filtrar informació entre orígens— i significa que la consola és la teva única font de veritat davant d'una fallada de CORS.

El segon paràmetre de fetch és un objecte d'opcions. Per crear una tasca:

Quatre punts:

• body mai és un objecte. Si li passes { titol: '…' } directament, el navegador el converteix amb String() i envia '[object Object]', exactament el mateix desastre que a localStorage. JSON.stringify és obligatori.
• JSON.stringify fa servir el toJSON de les teves instàncies, així que li pots passar una Tasca directament i viatjarà completa, camps privats inclosos. Un altre cop 05-03 rendint.
• L'id l'assigna el servidor, no el client. És la regla R1 del projecte, i en un sistema amb diversos usuaris és l'única manera de no col·lisionar.
• fetch no llança si el servidor rebutja les dades. Un 422 Unprocessable Entity amb la llista de camps invàlids arriba com a resposta normal; cal comprovar ok i llegir el cos de l'error.

Les opcions que més faràs servir:

Quan hi ha un fitxer pel mig —l'Iván vol adjuntar la foto de l'esbós—, JSON no serveix: és text. Es fa servir FormData, que ja coneixes de 06-07:

No posis Content-Type quan envies FormData. El navegador el genera sol, i hi afegeix el boundary —un separador aleatori— que el servidor necessita per trossejar el cos. Si l'escrius tu, el boundary falta i el servidor no pot llegir res. És una fallada desconcertant, perquè el codi «sembla més complet» amb la capçalera posada.

Comparació ràpida dels tres formats de cos:

Construir la cadena de consulta a mà és una font inesgotable de bugs de codificació:

Les classes URL i URLSearchParams codifiquen per tu:

Els membres útils d'URLSearchParams:

Un ajudant que faràs servir al projecte, saltant-se els filtres buits:

Aquell new URL(ruta, BASE) amb dos arguments resol rutes relatives contra una base, igual que ho fa un <a href>. Molt còmode per no concatenar barres.

Tard o d'hora escriuràs una petició perfecta i la consola dirà una cosa com:

CORS (Cross-Origin Resource Sharing) és el mecanisme que decideix si una pàgina d'un origen pot llegir respostes d'un altre origen. Per defecte, el navegador aplica la same-origin policy: pots enviar peticions a altres orígens, però no llegir-ne les respostes tret que aquell servidor ho autoritzi.

Per què existeix? Perquè el navegador envia automàticament les cookies de l'usuari. Sense aquesta política, qualsevol pàgina maliciosa que visitessis podria demanar https://elteubanc.example/api/saldo amb les teves cookies i llegir la resposta.

Hi ha dos tipus de petició creuada, i la diferència importa molt:

Petició simple: el navegador l'envia directament i després decideix si et deixa llegir la resposta. Es considera simple si fa servir GET, HEAD o POST, i les seves capçaleres són les corrents, amb un Content-Type limitat a text/plain, multipart/form-data o application/x-www-form-urlencoded.

Petició amb preflight: qualsevol altra cosa —PUT, PATCH, DELETE, o un POST amb Content-Type: application/json, o una capçalera Authorization— obliga el navegador a preguntar abans amb una petició OPTIONS.

Aquell OPTIONS extra explica dues coses que desconcerten: per què a la pestanya Network apareixen dues entrades per una sola crida, i per què de vegades la fallada passa «abans» que el servidor vegi la teva petició real.

Les capçaleres que controla el servidor:

I la conclusió que estalvia tardes senceres:

CORS no s'arregla des del client. Ni amb mode, ni amb capçaleres, ni amb trucs. L'aplica el navegador segons el que respon el servidor. Només hi ha tres sortides legítimes: que el servidor afegeixi les capçaleres, posar un proxy al teu mateix origen que reenviï les peticions, o servir API i web sota el mateix origen.

Dos matisos que es malinterpreten:

• mode: 'no-cors' no desactiva CORS. Et retorna una resposta opaca: status 0, ok false i cos illegible. Serveix per a casos molt concrets (precarregar en memòria cau des d'un service worker), no per saltar-se res.
• Les extensions tipus «Allow CORS» del navegador només desactiven la comprovació a la teva màquina. El teu codi continuarà trencat per a tota la resta. Fes-les servir, com a molt, per diagnosticar.
• Access-Control-Allow-Origin: * és incompatible amb credencials. Si envies cookies, el servidor ha d'anomenar el teu origen exacte.

Hi ha dues maneres que l'API sàpiga qui ets.

Token a la capçalera Authorization, el patró habitual de les APIs:

Cookies, que el navegador gestiona sol. Amb fetch cal demanar-les explícitament quan l'API és en un altre origen:

Quina triar? Reprenent l'advertiment de 07-01:

La recomanació no ha canviat: per a una sessió d'usuari real, cookie HttpOnly; Secure; SameSite=Lax, emesa i validada pel servidor. Si la teva API imposa un token a localStorage —cosa habitual—, assumeix que un XSS és un robatori de compte i tracta la prevenció d'XSS (06-02: textContent en lloc d'innerHTML) com a part de la seguretat de l'autenticació.

Tres regles més, curtes i no negociables:

• HTTPS sempre. Sobre http://, capçaleres i cossos viatgen llegibles per a qualsevol a la xarxa. Un token enviat per HTTP és un token públic.
• No fiquis mai claus d'API al codi del client. Tot el que arriba al navegador és visible. Si una clau ha de romandre secreta, la petició la fa el teu servidor, no la pàgina.
• Davant d'un 401, neteja la sessió local i envia a iniciar sessió. Reintentar amb un token caducat només genera soroll.

Ja pots escriure el germà de xarxa de RepositoriLocal. La mateixa responsabilitat —traduir entre el món exterior i el model— amb un altre mitjà.

Quatre decisions per subratllar:

• La frontera del model es respecta. El mòdul retorna instàncies de Tasca, no objectes plans, exactament com feia RepositoriLocal. La resta de l'aplicació no sap d'on venen les dades. Aquest és el sentit de tenir una carpeta dades/.
• comprovar està escrita una sola vegada. El parany de l'apartat 6 es neutralitza encapsulant-lo, no recordant-lo.
• esborrarTasca no crida json(). Un 204 No Content no té cos i json() llançaria.
• Aquí no hi ha try/catch. Aquest mòdul tradueix i propaga; qui decideix què mostrar a l'usuari és la vista. Com classificar i presentar aquells errors és justament el tema de 07-03.

I així se substitueixen per fi les funcions simulades de 05-06:

Aquí hi ha el patró que fa que una aplicació es percebi ràpida: local primer, xarxa després. L'emmagatzematge de 07-01 i la xarxa d'aquesta lliçó no competeixen; es complementen. (Aquell await despullat, sense try/catch ni estat de càrrega, encara està a mitges: el completaràs a la lliçó següent.)

api.tallernomada.example no existeix. Per practicar necessites un servidor real, i el més ràpid de muntar és json-server, que converteix un fitxer JSON en una API REST completa.

Amb aquest db.json, que és el backlog canònic del projecte:

Aquell fitxer dona immediatament totes les rutes que necessites:

Només has de canviar una línia al teu mòdul:

I json-server ja envia Access-Control-Allow-Origin: *, així que no barallaràs amb CORS mentre aprens. Altres opcions per practicar: https://jsonplaceholder.typicode.com (API pública de només lectura simulada), https://httpbin.org (retorna la teva pròpia petició, ideal per inspeccionar capçaleres) o https://httpstat.us/500 (retorna el codi que li demanis, perfecte per provar la gestió d'errors de la lliçó següent).

• Oblidar comprovar resposta.ok. L'error número u. Un 404 arriba com a èxit i la teva aplicació processa un missatge d'error com si fossin dades.
• Oblidar l'await de resposta.json(). Obtens una Promise i tot el que hi facis dona undefined.
• Passar un objecte com a body. Es converteix en '[object Object]'. JSON.stringify sempre.
• Posar Content-Type en enviar FormData. Trenca el boundary i el servidor no pot llegir el cos.
• Cridar .json() sobre un 204. No hi ha cos; llança. Comprova status === 204 o Content-Length.
• Llegir el cos dues vegades. TypeError: body stream already read. Fes servir resposta.clone() abans de la primera lectura.
• Concatenar paràmetres a mà. Un espai, un & o un accent trenquen la URL. Fes servir URL i URLSearchParams.
• Intentar arreglar CORS des del client. No es pot. Llegeix la consola, parla amb qui manté l'API o munta un proxy.
• Fer servir mode: 'no-cors' per «saltar-se» CORS. Retorna una resposta opaca i illegible.
• Ficar una clau d'API al JavaScript del client. És pública des del moment en què es descarrega.
• Consell: mira sempre la pestanya Network de les DevTools. Verb, codi, capçaleres, cos enviat i rebut, i l'OPTIONS del preflight. Gairebé tots els problemes de xarxa es diagnostiquen allà en trenta segons.
• Consell: fes servir await resposta.text() quan json() falli. Veuràs si el servidor ha retornat una pàgina HTML d'error en lloc de JSON.
• Consell: encapsula fetch en un únic mòdul. No el cridis mai solt des de la vista. Així la comprovació d'ok, la base de la URL i les capçaleres viuen en un sol lloc, i a 07-03 podràs afegir timeouts i reintents sense tocar la resta.
• Consell: al navegador, copy(await (await fetch(url)).json()) a la consola copia la resposta al porta-retalls. Molt útil per inspeccionar formats.

Exercici 1 — L'embolcall que no es pot oblidar. Escriu demanarJson(url, opcions = {}) que: faci el fetch; si resposta.ok és fals, llegeixi el cos com a text i llanci un Error el missatge del qual inclogui el status, el statusText i aquell text; si l'estat és 204 retorni null; i en cas contrari retorni await resposta.json(). Reescriu després llistarTasques i esborrarTasca fent-lo servir, i comprova que el codi queda més curt.

Exercici 2 — Cercador de tasques amb paràmetres. Escriu cercarTasques({ text, responsable, estats, ordre, pagina }) que construeixi la URL amb URLSearchParams, ometent els valors buits. estats és un array (['pendent', 'en-curs']) i ha de generar ?estat=pendent&estat=en-curs. La paginació fa servir _page i _limit, els paràmetres de json-server. Retorna { tasques, total } llegint el total de la capçalera X-Total-Count.

Exercici 3 — Sincronitzar el tauler local amb el servidor. Escriu sincronitzar(repositori, api) que: carregui el tauler local; demani al servidor la llista de tasques; i retorni un informe { nomesLocal, nomesServidor, enTotsDos, coincideixen } comparant per id, on coincideixen és el nombre de tasques presents als dos costats amb el mateix estat. No modifiquis res encara: només informa. Fes servir Map i els mètodes d'array de 04-05.

Solució 1

La comprovació del content-type és la que evita la pitjor de les fallades: un proxy corporatiu o una pantalla d'inici de sessió retornen HTML amb estat 200, i sense aquella línia el json() llançaria un SyntaxError incomprensible. Aquesta funció és el germen del demanarJson complet que construiràs a 07-03.

Solució 2

La diferència entre set i append és la clau: set reemplaça, així que un bucle amb set deixaria només l'últim estat. I compte amb X-Total-Count: en una API d'un altre origen, aquella capçalera només serà llegible si el servidor l'exposa amb Access-Control-Expose-Headers. Amb json-server a localhost no hi ha problema.

Solució 3

Els dos Map converteixen la comparació en operacions de cost constant en lloc de recórrer l'array remot per cada tasca local. I fixa't en el que revela el resultat: hi ha un conflicte. Què fer-hi —qui guanya quan local i servidor discrepen— és una decisió de producte, no tècnica, i hi tornaràs a 07-04 en parlar d'edició simultània.

Nómada Tasques ja sap parlar amb un servidor. Entens què significa AJAX i per què va canviar el web: demanar dades en segon pla i actualitzar només el que canvia, conservant scroll, focus i filtres, amb un JSON d'uns centenars de bytes en lloc d'un document HTML complet. Coneixes XMLHttpRequest prou per reconèixer-lo, i saps que fetch el substitueix en tot llevat del progrés de pujada, i que els seus dos buits —timeout i cancel·lació— s'omplen amb AbortController.

Tens l'HTTP que es fa servir cada dia: els verbs amb el seu significat i la seva idempotència (GET, PUT i DELETE sí, POST no), les rutes que anomenen recursos i no accions, les cinc famílies de codis amb la frontera decisiva entre el 4xx que arregla el client i el 5xx que no, i les capçaleres Content-Type, Accept i Authorization. Domines fetch i la seva doble espera —la primera promesa porta les capçaleres, la segona el cos—, l'objecte Response amb ok, status, headers i els cinc mètodes de cos, i la regla que el cos es llegeix una sola vegada tret que el clonis. I portes gravat el parany que defineix aquesta API: fetch no rebutja amb 404 ni amb 500; només rebutja si la petició no va arribar a completar-se. Per això la comprovació de resposta.ok no es recorda, s'encapsula.

Saps enviar dades amb method, headers i body —JSON.stringify obligatori, i Content-Type prohibit quan el cos és FormData—, construir URLs amb URL i URLSearchParams distingint set d'append, i explicar CORS: la same-origin policy, la petició simple davant del preflight OPTIONS que duplica les entrades a la pestanya Network, les capçaleres Access-Control-* que decideix el servidor, i la conclusió que estalvia tardes senceres —no s'arregla des del client, i mode: 'no-cors' només et dona una resposta opaca—. I tens clara la part de seguretat: HTTPS sempre, tokens preferiblement en cookie HttpOnly i no a localStorage, cap clau secreta al codi del client, i cap confiança en la validació del navegador.

En codi, el mòdul js/dades/api-tasques.js amb llistarTasques, obtenirTasca, crearTasca, actualitzarTasca i esborrarTasca, que retorna instàncies de Tasca i no objectes plans, igual que feia RepositoriLocal: la capa dades/ és una frontera, i la resta de l'aplicació no sap si les dades venen del disc o de la xarxa. I un json-server a localhost:3000 amb el backlog canònic perquè puguis practicar contra un servidor de debò, perquè api.tallernomada.example és i continuarà sent fictici.

Ara bé: aquell codi funciona només quan tot va bé. I a la xarxa res va bé tota l'estona. El wifi del taller cau a mitja POST; l'API triga quinze segons i la Marta prem el botó tres vegades; el servidor retorna un 503 perquè estan desplegant; l'Iván escriu al cercador i es llancen vuit peticions de les quals arriba abans la penúltima, deixant a la pantalla resultats que no corresponen al que va escriure. Cap d'aquelles situacions la cobreix el que has escrit avui: no hi ha timeout, no hi ha cancel·lació, no hi ha reintents, no hi ha estat de càrrega i no hi ha manera de dir a l'usuari què ha passat. Això és exactament el que separa una demostració d'una aplicació, i és el tema de Peticions Robustes: Errors, Timeouts i AbortController, on AbortController —presentat de passada a 06-04— per fi ocuparà el lloc que li correspon.