⚙️ Request Configuration Options

The Options Object

Every fetch you've written so far used a single argument. The full signature is fetch(url, options), where options is a plain object whose properties fine-tune the request:

fetch('https://api.example.com/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Ada', email: 'ada@example.com' }),
})
  .then((response) => response.json())
  .then((data) => console.log(data));

💡 An analogy: If the URL is the address on an envelope, the options object is everything else that governs delivery — first class or ground (method), the notes on the outside (headers), the contents inside (body), whether it's tracked and signed-for (credentials), and a way to recall it mid-transit (signal).

HTTP Methods with method

The method property sets the HTTP verb. It defaults to 'GET'. Each verb signals a different intent to the server, and REST APIs lean on that convention heavily.

// GET (default) — just read
await fetch('https://api.example.com/users');

// POST — create
await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Alice', email: 'alice@example.com' }),
});

// PATCH — partial update
await fetch('https://api.example.com/users/123', {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'new@example.com' }),
});

// DELETE — remove
await fetch('https://api.example.com/users/123', { method: 'DELETE' });

Request Headers with headers

Headers are metadata about your request — who you are, what format you're sending, what you'd like back. You can pass a plain object or a Headers instance.

// Plain object — simplest
await fetch('https://api.example.com/data', {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer eyJhbGciOiJIUzI1Ni...',
    'Accept': 'application/json',
  },
});

// Headers object — handy for building headers dynamically
const headers = new Headers();
headers.append('Content-Type', 'application/json');
headers.set('Authorization', `Bearer ${token}`);
if (headers.has('Authorization')) {
  console.log(headers.get('Authorization'));
}
await fetch('https://api.example.com/data', { headers });

The Request Body with body

The body carries the data you're sending, for methods like POST, PUT, and PATCH. Its type determines how you prepare it — and often which Content-Type to set (or not set).

JSON — the everyday case

await fetch('https://api.example.com/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'John Doe', age: 30 }),
});

FormData — files and multipart

const formData = new FormData();
formData.append('username', 'johndoe');
formData.append('avatar', fileInput.files[0]);

await fetch('https://api.example.com/profile', {
  method: 'POST',
  body: formData, // note: do NOT set Content-Type yourself
});

URLSearchParams — form-encoded data

const params = new URLSearchParams();
params.append('search', 'query term');
params.append('sort', 'ascending');

await fetch('https://api.example.com/search', {
  method: 'POST',
  body: params, // sets application/x-www-form-urlencoded automatically
});

Mode & Credentials

mode — cross-origin behavior

The mode option governs how the request deals with CORS (Cross-Origin Resource Sharing), the browser rule that a page may only read responses from other origins when the server opts in.

• 'cors' (default) — a normal cross-origin request; the server must send the right Access-Control-* headers for you to read the response.
• 'same-origin' — fail outright if the URL is on a different origin.
• 'no-cors' — allowed for a narrow set of "simple" requests, but you get an opaque response whose body you cannot read.

credentials — cookies and auth

This controls whether cookies and HTTP-auth headers ride along with the request:

• 'same-origin' (default) — send credentials only to the same origin.
• 'include' — always send them, even cross-origin.
• 'omit' — never send them.

// Send the session cookie to a cross-origin API
await fetch('https://api.example.com/profile', {
  credentials: 'include',
});

Cache, Redirect & Signal

cache — talking to the HTTP cache

The cache option decides how the request interacts with the browser's HTTP cache:

redirect

Controls redirect handling: 'follow' (default, follow automatically), 'error' (reject on a redirect), or 'manual' (hand you the redirect to deal with yourself).

signal — cancellation and timeouts

Perhaps the most useful advanced option. An AbortController produces a signal you pass into fetch; calling controller.abort() cancels the in-flight request. This powers timeouts and "cancel the old search when a new keystroke arrives" patterns.

// A fetch that times out after 5 seconds
async function fetchWithTimeout(url, ms = 5000) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), ms);

  try {
    const response = await fetch(url, { signal: controller.signal });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return await response.json();
  } catch (error) {
    if (error.name === 'AbortError') {
      throw new Error(`Request timed out after ${ms}ms`);
    }
    throw error;
  } finally {
    clearTimeout(timeoutId);
  }
}

Hands-on Exercise

async function request(url, options = {}) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), 8000);

  const defaults = {
    headers: { 'Content-Type': 'application/json' },
    credentials: 'same-origin',
  };

  try {
    const response = await fetch(url, {
      ...defaults,
      ...options,
      headers: { ...defaults.headers, ...options.headers },
      signal: controller.signal,
    });

    if (!response.ok) {
      throw new Error(`Request failed: ${response.status}`);
    }
    return await response.json();
  } catch (error) {
    if (error.name === 'AbortError') throw new Error('Request timed out');
    throw error;
  } finally {
    clearTimeout(timeoutId);
  }
}

// GET
const post = await request('https://jsonplaceholder.typicode.com/posts/1');

// POST
const created = await request('https://jsonplaceholder.typicode.com/posts', {
  method: 'POST',
  body: JSON.stringify({ title: 'Hello', body: 'World', userId: 1 }),
});

Best Practices

Summary & Quiz

📚 Further Reading

• MDN — fetch() parameters
• MDN — AbortController
• MDN — Cross-Origin Resource Sharing (CORS)

🚀 What's Next?

You now control exactly how a request goes out. Next we turn to what comes back — processing the Response object in depth: status properties, headers, body methods, cloning, and streaming.