The previous lesson delivered half a promise: Nómada Tasks now survives F5. But Marta, Iván and Lucía still each have their own localStorage, with their own version of the board, with no way of seeing one another. The other half —making the board the same one for the whole team— requires the data to live on a server and the browser to know how to talk to it without reloading the page. That is AJAX, and the modern tool for doing it is fetch. In this lesson you will learn what AJAX changed on the web, review the HTTP you actually need (verbs, status codes and headers), master fetch and the Response object with its most famous trap —a 404 does not reject the promise—, send data as JSON and as FormData, build URLs with parameters, understand CORS well enough not to lose an afternoon, and write js/data/tasks-api.js, the network sibling of the local repository. And you will finally retire those readSimulatedBacklog() and saveSimulatedReport() functions from 05-06 that faked latency with setTimeout.

1. What AJAX is and what it changed
2. XMLHttpRequest, the ancestor
3. HTTP in ten minutes: verbs, paths, status codes and headers
4. fetch: the minimal request
5. The Response object and the body methods
6. The fundamental trap: fetch does not reject on 404 or 500
7. Sending data: method, headers and body
8. Sending FormData and files
9. Query parameters with URL and URLSearchParams
10. CORS: why the browser blocks you
11. Authentication: Authorization and credentials
12. Nómada Tasks: js/data/tasks-api.js
13. Real practice: json-server on your machine
14. Common Mistakes and Tips
15. Exercises
16. Conclusion

AJAX stands for Asynchronous JavaScript And XML, a name coined in 2005 that today is half a lie: hardly anyone uses XML —JSON is used instead— and the technique applies to far more than XML. What the acronym names is still current: asking the server for data from JavaScript, without reloading the page, and updating only the part of the DOM that changes.

Compare the two models:

What AJAX makes possible, in Nómada Tasks terms: Marta presses the advance-status button, the card moves column, and neither the scroll nor the assignee filter nor the focus is lost. The cycle state → render → event → new state → render that you built in 06-06 is still in charge; the only thing that changes is that part of the "new state" now arrives from the server.

And there is something that does not change and is worth saying early: the server is still in charge. An AJAX request is no more secure than a form; the user can craft whatever they like from the console. All client-side validation is a courtesy; the real one is on the server.

Before fetch there was XMLHttpRequest (XHR), available since the early 2000s. You will see it in old code and it is worth recognizing:

It is the callback style from 05-05 taken to the extreme: no promises, no async/await, and the famous readyState with its five numeric values. The comparison:

Today you use fetch except in two cases: when you need an upload progress bar for a large file, or when you are maintaining old code. The two gaps in fetch —timeout and cancellation— are covered by AbortController, and that is the next lesson.

An HTTP request has four parts: a verb, a path, some headers and sometimes a body. The response has a status code, its own headers and its body.

Idempotent means that repeating the same request leaves the system in the same state as doing it once. A PUT of task 6 with the same data, a thousand times, leaves one task 6 with that data. POST a thousand times creates a thousand tasks. That distinction looks theoretical until in 07-03 you decide which requests can be retried without fear.

A REST API names things, not actions, and lets the verb say what to do with them:

A common antipattern is POST /v1/createTask or GET /v1/deleteTask?id=6. The second one is especially bad: a GET must not change anything, and any search engine or browser prefetcher could fire it.

The domain https://api.tallernomada.example/v1 that we will use throughout this lesson is fictional. The .example TLD is reserved by IANA precisely for documentation and will never resolve. In section 13 you will set up a real server on your machine to practice with.

They are grouped into families, and knowing the families is more than enough:

The boundary between 4xx and 5xx is what governs your error handling: a 4xx is fixed by the client (correct the data, sign in, stop insisting); a 5xx is not fixed by the client (retry later and report it). Two pairs that are often confused:

• 401 Unauthorized means "I do not know who you are" (the credential is missing or expired). 403 Forbidden means "I know who you are and you may not". The first one calls for signing in; the second one does not.
• 204 No Content is a success with no body. Calling .json() on it throws, because there is nothing to parse. You will bear that in mind in deleteTask().

The most frequent beginner mistake with headers: sending a JSON body without Content-Type: application/json. Many servers interpret it as plain text and return a baffling 400.

fetch(url, options) returns a promise that resolves with a Response object as soon as the response headers arrive. With what you know from 05-06, it reads effortlessly:

Two awaits, and each waits for something different. This is what is hardest at first:

The first promise resolves with the headers; the body may still be arriving. That is why response.json() is another asynchronous operation and needs its own await. Forgetting it produces the most common error of all:

Response describes the complete response:

And the body methods, all asynchronous because they all return promises:

Header names are case-insensitive: headers.get('Content-Type') and headers.get('content-type') are the same thing.

One rule that catches people out: the body can only be read once. It is a stream, and once consumed, that is that.

If you need to read it twice —for example, to try json() and, if it fails, look at the text() to debug— clone it first:

That pattern will save your day when a proxy returns an HTML error page where you expected JSON.

This is the thing to know about fetch, and the one that has produced the most broken code:

The fetch promise only rejects if the request never completed: network down, DNS that does not resolve, blocked by CORS, request cancelled. If the server responds —even if it responds 404, 403 or 500— the promise resolves normally.

The catch does not run. response.json() parses the error body without complaining, and your application carries on with rubbish. The fix is to always check ok:

The table that explains the reasoning behind the design:

The logic of the design is defensible: fetch promises to make the HTTP request, and a 404 is a successfully made HTTP request whose answer is "it does not exist". That it is defensible does not stop it being the number-one cause of network bugs. In section 12 we will encapsulate the check once and for all so we never forget it again.

Notice as well the detail in the last diagnostic row: when CORS blocks a request, JavaScript receives a generic TypeError with no details. The real reason only appears in the browser console. It is deliberate —giving details would leak information across origins— and it means that the console is your only source of truth when facing a CORS failure.

The second parameter of fetch is an options object. To create a task:

Four points:

• body is never an object. If you pass it { title: '…' } directly, the browser converts it with String() and sends '[object Object]', exactly the same disaster as in localStorage. JSON.stringify is compulsory.
• JSON.stringify uses the toJSON of your instances, so you can pass it a Task directly and it will travel complete, private fields included. 05-03 paying off once again.
• The id is assigned by the server, not the client. It is rule R1 of the project, and in a system with several users it is the only way not to collide.
• fetch does not throw if the server rejects the data. A 422 Unprocessable Entity with the list of invalid fields arrives as a normal response; you have to check ok and read the error body.

The options you will use most:

When there is a file involved —Iván wants to attach a photo of the sketch— JSON is no use: it is text. You use FormData, which you already know from 06-07:

Do not set Content-Type when you send FormData. The browser generates it on its own, and adds the boundary —a random separator— that the server needs in order to split the body into parts. If you write it yourself, the boundary is missing and the server cannot read anything. It is a baffling failure, because the code "looks more complete" with the header in place.

A quick comparison of the three body formats:

Building the query string by hand is an endless source of encoding bugs:

The URL and URLSearchParams classes encode for you:

The useful members of URLSearchParams:

A helper you will use in the project, skipping empty filters:

That new URL(path, BASE) with two arguments resolves relative paths against a base, exactly as an <a href> does. Very handy for not having to concatenate slashes.

Sooner or later you will write a perfect request and the console will say something like:

CORS (Cross-Origin Resource Sharing) is the mechanism that decides whether a page from one origin may read responses from another origin. By default, the browser applies the same-origin policy: you can send requests to other origins, but not read their responses unless that server authorizes it.

Why does it exist? Because the browser automatically sends the user's cookies. Without this policy, any malicious page you visited could request https://yourbank.example/api/balance with your cookies and read the response.

There are two kinds of cross-origin request, and the difference matters a lot:

Simple request: the browser sends it directly and then decides whether to let you read the response. It counts as simple if it uses GET, HEAD or POST, and its headers are the ordinary ones, with a Content-Type limited to text/plain, multipart/form-data or application/x-www-form-urlencoded.

Request with preflight: anything else —PUT, PATCH, DELETE, or a POST with Content-Type: application/json, or an Authorization header— forces the browser to ask first with an OPTIONS request.

That extra OPTIONS explains two things that puzzle people: why two entries appear in the Network tab for a single call, and why the failure sometimes happens "before" the server sees your real request.

The headers the server controls:

And the conclusion that saves whole afternoons:

CORS cannot be fixed from the client. Not with mode, not with headers, not with tricks. The browser applies it according to what the server responds. There are only three legitimate ways out: the server adds the headers, you put a proxy on your own origin that forwards the requests, or you serve the API and the web app under the same origin.

Two nuances that get misread:

• mode: 'no-cors' does not switch CORS off. It gives you an opaque response: status 0, ok false and an unreadable body. It is for very specific cases (precaching in a service worker), not for bypassing anything.
• "Allow CORS" browser extensions only disable the check on your machine. Your code will still be broken for everybody else. Use them, at most, to diagnose.
• Access-Control-Allow-Origin: * is incompatible with credentials. If you send cookies, the server has to name your exact origin.

There are two ways for the API to know who you are.

A token in the Authorization header, the usual pattern for APIs:

Cookies, which the browser manages on its own. With fetch you have to ask for them explicitly when the API is on another origin:

Which one to choose? Picking up the warning from 07-01:

The recommendation has not changed: for a real user session, an HttpOnly; Secure; SameSite=Lax cookie, issued and validated by the server. If your API forces a token in localStorage —which is common— assume that an XSS is account theft and treat XSS prevention (06-02: textContent instead of innerHTML) as part of authentication security.

Three more rules, short and non-negotiable:

• HTTPS always. Over http://, headers and bodies travel readable by anyone on the network. A token sent over HTTP is a public token.
• Never put API keys in client code. Everything that reaches the browser is visible. If a key must stay secret, your server makes the request, not the page.
• On a 401, clear the local session and send the user to sign in. Retrying with an expired token only generates noise.

You can now write the network sibling of LocalRepository. The same responsibility —translating between the outside world and the model— through a different medium.

Four decisions worth underlining:

• The model boundary is respected. The module returns Task instances, not plain objects, exactly as LocalRepository did. The rest of the application does not know where the data comes from. That is the point of having a data/ folder.
• check is written only once. The trap from section 6 is neutralized by encapsulating it, not by remembering it.
• deleteTask does not call json(). A 204 No Content has no body and json() would throw.
• There is no try/catch here. This module translates and propagates; the one that decides what to show the user is the view. How to classify and present those errors is precisely the subject of 07-03.

And this is how the simulated functions from 05-06 are finally replaced:

There is the pattern that makes an application feel fast: local first, network afterwards. The storage from 07-01 and the network from this lesson do not compete; they complement each other. (That naked await, with no try/catch and no loading state, is still half-finished: you will complete it in the next lesson.)

api.tallernomada.example does not exist. To practice you need a real server, and the quickest one to set up is json-server, which turns a JSON file into a complete REST API.

With this db.json, which is the project's canonical backlog:

That file immediately gives you every route you need:

You only have to change one line in your module:

And json-server already sends Access-Control-Allow-Origin: *, so you will not be fighting CORS while you learn. Other options for practicing: https://jsonplaceholder.typicode.com (a simulated read-only public API), https://httpbin.org (returns your own request, ideal for inspecting headers) or https://httpstat.us/500 (returns whatever code you ask for, perfect for testing the next lesson's error handling).

• Forgetting to check response.ok. The number-one error. A 404 arrives as a success and your application processes an error message as if it were data.
• Forgetting the await on response.json(). You get a Promise and everything you do with it gives undefined.
• Passing an object as body. It becomes '[object Object]'. Always JSON.stringify.
• Setting Content-Type when sending FormData. It breaks the boundary and the server cannot read the body.
• Calling .json() on a 204. There is no body; it throws. Check status === 204 or Content-Length.
• Reading the body twice. TypeError: body stream already read. Use response.clone() before the first read.
• Concatenating parameters by hand. A space, an & or an accent breaks the URL. Use URL and URLSearchParams.
• Trying to fix CORS from the client. You cannot. Read the console, talk to whoever maintains the API, or set up a proxy.
• Using mode: 'no-cors' to "bypass" CORS. It returns an opaque, unreadable response.
• Putting an API key in the client's JavaScript. It is public from the moment it is downloaded.
• Tip: always look at the Network tab in DevTools. Verb, status code, headers, body sent and received, and the preflight OPTIONS. Almost every network problem is diagnosed there in thirty seconds.
• Tip: use await response.text() when json() fails. You will see whether the server returned an HTML error page instead of JSON.
• Tip: encapsulate fetch in a single module. Never call it loose from the view. That way the ok check, the URL base and the headers live in one place, and in 07-03 you will be able to add timeouts and retries without touching anything else.
• Tip: in the browser, copy(await (await fetch(url)).json()) in the console copies the response to the clipboard. Very useful for inspecting formats.

Exercise 1 — The wrapper you cannot forget. Write fetchJson(url, options = {}) that: performs the fetch; if response.ok is false, reads the body as text and throws an Error whose message includes the status, the statusText and that text; if the status is 204 returns null; and otherwise returns await response.json(). Then rewrite listTasks and deleteTask using it, and check that the code comes out shorter.

Exercise 2 — Task search with parameters. Write searchTasks({ text, assignee, statuses, sortBy, page }) that builds the URL with URLSearchParams, omitting empty values. statuses is an array (['pending', 'in-progress']) and must generate ?status=pending&status=in-progress. Pagination uses _page and _limit, the json-server parameters. Return { tasks, total }, reading the total from the X-Total-Count header.

Exercise 3 — Syncing the local board with the server. Write sync(repository, api) that: loads the local board; asks the server for the list of tasks; and returns a report { onlyLocal, onlyServer, inBoth, matching } comparing by id, where matching is the number of tasks present on both sides with the same status. Do not modify anything yet: just report. Use Map and the array methods from 04-05.

Solution 1

The content-type check is what prevents the worst kind of failure: a corporate proxy or a sign-in screen returns HTML with status 200, and without that line json() would throw an incomprehensible SyntaxError. This function is the seed of the complete fetchJson you will build in 07-03.

Solution 2

The difference between set and append is the key: set replaces, so a loop with set would leave only the last status. And watch out for X-Total-Count: on an API from another origin, that header will only be readable if the server exposes it with Access-Control-Expose-Headers. With json-server on localhost there is no problem.

Solution 3

The two Maps turn the comparison into constant-cost operations instead of walking the remote array for every local task. And notice what the result reveals: there is a conflict. What to do about it —who wins when local and server disagree— is a product decision, not a technical one, and you will come back to it in 07-04 when we talk about simultaneous editing.

Nómada Tasks now knows how to talk to a server. You understand what AJAX means and why it changed the web: asking for data in the background and updating only what changes, preserving scroll, focus and filters, with a few hundred bytes of JSON instead of a complete HTML document. You know XMLHttpRequest well enough to recognize it, and you know that fetch replaces it in everything except upload progress, and that its two gaps —timeout and cancellation— are filled by AbortController.

You have the HTTP that gets used every day: the verbs with their meaning and their idempotence (GET, PUT and DELETE yes, POST no), the paths that name resources rather than actions, the five families of status codes with the decisive boundary between the 4xx the client fixes and the 5xx it does not, and the Content-Type, Accept and Authorization headers. You have mastered fetch and its double wait —the first promise brings the headers, the second the body—, the Response object with ok, status, headers and the five body methods, and the rule that the body is read only once unless you clone it. And you have engraved the trap that defines this API: fetch does not reject on 404 or on 500; it only rejects if the request never completed. That is why the response.ok check is not remembered, it is encapsulated.

You know how to send data with method, headers and body —JSON.stringify compulsory, and Content-Type forbidden when the body is FormData—, how to build URLs with URL and URLSearchParams telling set apart from append, and how to explain CORS: the same-origin policy, the simple request versus the OPTIONS preflight that doubles the entries in the Network tab, the Access-Control-* headers that the server decides, and the conclusion that saves whole afternoons —it cannot be fixed from the client, and mode: 'no-cors' only gives you an opaque response. And you are clear about the security side: HTTPS always, tokens preferably in an HttpOnly cookie and not in localStorage, no secret key in client code, and no trust whatsoever in browser-side validation.

In code, the module js/data/tasks-api.js with listTasks, getTask, createTask, updateTask and deleteTask, which returns Task instances and not plain objects, exactly as LocalRepository did: the data/ layer is a boundary, and the rest of the application does not know whether the data comes from disk or from the network. Plus a json-server on localhost:3000 with the canonical backlog so you can practice against a real server, because api.tallernomada.example is and will remain fictional.

That said: that code works only when everything goes well. And on a network nothing goes well all the time. The workshop wifi drops in the middle of a POST; the API takes fifteen seconds and Marta presses the button three times; the server returns a 503 because a deployment is under way; Iván types in the search box and eight requests are fired, of which the second-to-last arrives first, leaving results on screen that do not match what he typed. None of those situations is covered by what you have written today: there is no timeout, no cancellation, no retries, no loading state and no way of telling the user what happened. That is exactly what separates a demo from an application, and it is the subject of Robust Requests: Errors, Timeouts and AbortController, where AbortController —introduced in passing in 06-04— will finally take its rightful place.