fetch: talking to servers

HTTP in one paragraph

HTTP is the language browsers and servers use. A client sends a request: a method (GET to read, POST to create, PUT/PATCH to update, DELETE to remove), a URL, headers (extra information like Content-Type) and sometimes a body (the data). The server sends back a response: a status code (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Server Error), headers and a body, very often JSON.

A GET request

async function getTrain(number) {
  const response = await fetch(`https://api.example.com/trains/${number}`);
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
  return response.json();     // also a promise: reading the body takes time
}

The Response object

The body can be read only once. Calling json() and then text() on the same response throws "body used already".

Sending JSON with POST

async function createOrder(order) {
  const response = await fetch('https://api.example.com/orders', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(order),
  });
  if (!response.ok) throw new Error(`Could not create order: ${response.status}`);
  return response.json();  // e.g. { id: 'OD1023', status: 'PLACED' }
}

Timeouts and cancelling with AbortController

async function fetchWithTimeout(url, ms) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), ms);
  try {
    const response = await fetch(url, { signal: controller.signal });
    return await response.json();
  } finally {
    clearTimeout(timer);
  }
}
// Newer engines also offer the shortcut fetch(url, { signal: AbortSignal.timeout(5000) }).

Aborting really stops the request (unlike Promise.race, which only stops waiting). The fetch promise then rejects with an error named AbortError.

A complete pattern

1. Show a loading state.
2. await fetch inside try.
3. If !response.ok, throw an error with the status.
4. Parse JSON and check the shape you expect.
5. catch: show a friendly message and log the details.
6. finally: hide the loading state.

CORS in one line

A web page can only read responses from another domain if that server allows it with CORS headers (Access-Control-Allow-Origin). A CORS error is fixed on the SERVER, not in your fetch call. Node.js scripts are not limited by CORS.