Fetch API

Making HTTP requests from JavaScript — fetch(), Request, Response, Headers, streaming, and abort.

What it is, in plain English: The Fetch API is the modern way to make HTTP requests from JavaScript. fetch(url) returns a Promise that resolves to a Response object. You then call response.json(), response.text(), or response.blob() to read the body — these also return Promises. Fetch is available in all modern browsers and in Node.js from v18.

Where this bites you

A streamed response arrives in chunks, and chunk boundaries have nothing to do with your lines. The network can split a message anywhere, even in the middle of a JSON string. Code that splits each chunk on "\n" and parses every line works on localhost, where chunks are tidy, and then crashes in production with SyntaxError: Unterminated string in JSON.

async function readTokens() {
  const res    = await fetch("/api/ai/stream");
  const reader = res.body.getReader();
  const dec    = new TextDecoder();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const lines = dec.decode(value).split("\n");   // assumes each chunk holds whole lines
    for (const line of lines) {
      if (line.startsWith("data: ")) {
        console.log(JSON.parse(line.slice(6)).token);
      }
    }
  }
}
readTokens().catch(e => console.log(`${e.name}: ${e.message}`));
// server sends 'data: {"token":"Hel"}\ndata: {"tok' and then 'en":"lo"}\n'
// Hel
// SyntaxError: Unterminated string in JSON at position 5 (line 1 column 6)

Making HTTP requests from the browser

Before fetch(), you needed XMLHttpRequest — verbose, callback-based, and painful. fetch() is clean, Promise-based, and works everywhere.

The simplest GET request

// fetch() returns a Promise → use await inside an async function
async function getUser() {
  const response = await fetch("https://api.example.com/user/1");

  // IMPORTANT: fetch() only rejects on network failure, not HTTP errors.
  // A 404 or 500 still "succeeds" — you must check response.ok:
  if (!response.ok) {
    throw new Error(`Failed: ${response.status}`);
  }

  const user = await response.json();  // parse the JSON body
  console.log(user.name);
}

getUser();

POST, PUT, DELETE — sending data

// POST with JSON body:
async function createPost(data) {
  const response = await fetch("https://api.example.com/posts", {
    method:  "POST",
    headers: { "Content-Type": "application/json" },
    body:    JSON.stringify(data),
  });
  return response.json();
}

// PUT — update a resource:
await fetch(`/api/users/${id}`, {
  method:  "PUT",
  headers: { "Content-Type": "application/json" },
  body:    JSON.stringify({ name: "Updated Name" }),
});

// DELETE:
await fetch(`/api/users/${id}`, { method: "DELETE" });

// With authentication header:
await fetch("/api/protected", {
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json",
  },
});

Handling errors properly

async function apiFetch(url, options = {}) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      // Try to get error details from the response body:
      const error = await response.json().catch(() => ({}));
      throw new Error(error.message ?? `HTTP ${response.status}`);
    }

    return response.json();
  } catch (e) {
    if (e.name === "TypeError") {
      // Network error (offline, DNS failure, CORS blocked):
      throw new Error("Network error — check your connection");
    }
    throw e;
  }
}

// Usage:
try {
  const user = await apiFetch("/api/user/1");
  console.log(user.name);
} catch (e) {
  console.error(e.message);
}

Uploading files

// Use FormData — don't set Content-Type (browser sets it with boundary):
const form = document.querySelector("form");
const data = new FormData(form);

// Or build FormData manually:
const fd = new FormData();
fd.append("file", fileInput.files[0]);
fd.append("userId", "42");

const response = await fetch("/api/upload", {
  method: "POST",
  body:   fd,   // ← no Content-Type header! browser handles it
});

Try It Yourself

// fetch() — the modern way to make HTTP requests
// Returns a Promise that resolves to a Response

async function example() {
  // Basic GET request:
  const response = await fetch("https://jsonplaceholder.typicode.com/users/1");

// Check if successful:
  if (!response.ok) {
    throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
  }

// Parse the JSON body (also async):
  const user = await response.json();
  console.log("User:", user.name, "|", user.email);

// POST with JSON body:
  const created = await fetch("https://jsonplaceholder.typicode.com/posts", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ title: "Hello", body: "World", userId: 1 }),
  });
  const newPost = await created.json();
  console.log("Created post id:", newPost.id);

// Reading response metadata:
  console.log("Status:", response.status);     // 200
  console.log("Content-Type:", response.headers.get("content-type"));
}

example();

// Response body methods:
// response.json()        → parse body as JSON
// response.text()        → body as string
// response.blob()        → body as Blob (binary)
// response.arrayBuffer() → body as ArrayBuffer
// response.formData()    → body as FormData

// AbortController — cancel a request:
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);  // abort after 5 seconds

fetch("https://jsonplaceholder.typicode.com/posts", {
  signal: controller.signal
}).catch(e => {
  if (e.name === "AbortError") console.log("Request was aborted");
});

Abort, streaming, and request/response objects

AbortController — cancel requests

// Timeout pattern:
async function fetchWithTimeout(url, ms = 5000) {
  const controller = new AbortController();
  const timeout    = setTimeout(() => controller.abort(), ms);

  try {
    const res = await fetch(url, { signal: controller.signal });
    clearTimeout(timeout);
    return res.json();
  } catch (e) {
    if (e.name === "AbortError") throw new Error(`Request timed out after ${ms}ms`);
    throw e;
  }
}

// Cancel on navigation (React cleanup pattern):
useEffect(() => {
  const controller = new AbortController();
  fetch("/api/data", { signal: controller.signal })
    .then(r => r.json())
    .then(setData)
    .catch(e => { if (e.name !== "AbortError") console.error(e); });
  return () => controller.abort();  // cleanup: abort on unmount
}, []);

Streaming responses

// Read large responses incrementally (great for AI streaming, file downloads):
async function streamResponse(url) {
  const response = await fetch(url);
  const reader   = response.body.getReader();
  const decoder  = new TextDecoder();
  let   result   = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const chunk = decoder.decode(value, { stream: true });
    result += chunk;
    process(chunk);  // handle each chunk as it arrives
  }
  return result;
}

// Server-Sent Events / AI streaming (OpenAI-style):
const res = await fetch("/api/ai/stream", { method: "POST", body: JSON.stringify(prompt) });
const reader = res.body.getReader();
const dec    = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const lines = dec.decode(value).split("\n");  // ⚠ a chunk can end mid-line: see the buffered version below
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      displayToken(data.token);  // show each token as it streams
    }
  }
}

The AI streaming loop above has exactly this problem. Keep a buffer: add each decoded chunk to it, split on newlines, process only the complete lines, and keep the last, possibly unfinished, piece for the next chunk. Decode with { stream: true } as well, as the first example does. That way a multi-byte character split across two chunks isn't garbled either:

async function readTokens() {
  const res    = await fetch("/api/ai/stream");
  const reader = res.body.getReader();
  const dec    = new TextDecoder();
  let buffer   = "";
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += dec.decode(value, { stream: true });
    const lines = buffer.split("\n");
    buffer = lines.pop();            // the last piece may be incomplete: keep it for the next chunk
    for (const line of lines) {
      if (line.startsWith("data: ")) {
        console.log(JSON.parse(line.slice(6)).token);
      }
    }
  }
}
readTokens().catch(e => console.log(`${e.name}: ${e.message}`));
// Hel
// lo

Request and Response objects

// Build reusable Request objects:
const baseRequest = new Request("https://api.example.com", {
  headers: new Headers({
    "Authorization": `Bearer ${token}`,
    "Accept": "application/json",
  }),
});

// Clone and customise for each endpoint:
const userReq = new Request(`${baseRequest.url}/users/1`, baseRequest);
const response = await fetch(userReq);

// Response is a stream — can only be consumed once.
// Clone if you need to read it twice:
const res   = await fetch(url);
const clone = res.clone();
const json  = await res.json();
const text  = await clone.text();

CORS, credentials, and the Fetch spec

CORS — Cross-Origin Resource Sharing

// By default, fetch() omits credentials (cookies, auth) on cross-origin requests:
fetch(url);  // credentials: "same-origin" (default)

// Include credentials on cross-origin:
fetch(url, { credentials: "include" });
// Server must respond with: Access-Control-Allow-Credentials: true
// AND Access-Control-Allow-Origin: https://your-site.com (not *)

// Preflighted requests — browser sends OPTIONS first for:
// - Methods other than GET/POST/HEAD
// - Non-simple headers (e.g. Authorization, Content-Type: application/json)
// - Requests with credentials
// Server must handle OPTIONS with CORS headers

Fetch vs XMLHttpRequest

// fetch() advantages:
// - Promise-based (no callback hell)
// - Cleaner API
// - Response streaming via ReadableStream
// - Works in Service Workers

// fetch() limitations vs XHR:
// - No upload progress (XHR has xhr.upload.onprogress)
// - No synchronous mode (XHR has { async: false } — avoid it anyway)
// - Doesn't send cookies by default cross-origin

// Upload progress workaround with fetch:
// Use Streams API (experimental) or fall back to XHR for progress

Fetch in the spec (Fetch Standard — WHATWG)

The Fetch Standard (fetch.spec.whatwg.org) defines the Request, Response, Headers, and Body interfaces. The fetch() method initiates a fetch algorithm which goes through: URL parsing → header validation → CORS check → Connection → HTTP/2 or HTTP/1.1 → response body streaming via ReadableStream → Body mixin consumption (json/text/arrayBuffer/blob/formData each read the stream once).

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.