new Request() — Methode · JavaScript-Referenz

Signatur

new Request(input, options)

Beschreibung

Mit new Request() beschreibst du eine HTTP-Anfrage als eigenständiges Objekt. Dazu gehören URL, Methode, Header, Body, Cache-Verhalten, Credentials-Modus und weitere Optionen. Das Objekt lässt sich direkt an fetch() übergeben, im Cache-Storage als Schlüssel verwenden oder in einem Service Worker verändern und weiterleiten.

Nützlich ist der Konstruktor vor allem, wenn eine Anfrage einmal definiert und mehrfach verwendet werden soll, etwa in Hilfsfunktionen, Middleware oder Tests. Wichtig ist er auch, wenn du eine bestehende Anfrage kopieren und dabei einzelne Eigenschaften ändern willst: Übergibst du als input ein vorhandenes Request-Objekt, dienen dessen Werte als Grundlage, und die Angaben in options überschreiben sie.

Ein Request ist in großen Teilen unveränderlich. Eigenschaften wie url oder method sind nur lesbar. Der Body lässt sich nur einmal auslesen. Soll dieselbe Anfrage mit Body mehrmals verwendet werden, erzeugst du vorher mit request.clone() eine Kopie.

Parameter

Name	Typ	Default	Beschreibung
$input Pflicht	string \| URL \| Request		Ziel der Anfrage: eine URL als String oder als `URL`-Objekt, oder ein bestehendes `Request`-Objekt, das kopiert wird. Relative URLs werden relativ zur Basis-URL des Dokuments bzw. Workers aufgelöst.
$options	RequestInit	{}	Optionales Objekt mit Einstellungen, u. a.: `method`: HTTP-Methode, Standard `"GET"` `headers`: `Headers`, Objekt oder Array von Paaren `body`: `string`, `Blob`, `ArrayBuffer`, `TypedArray`, `DataView`, `FormData`, `URLSearchParams` oder `ReadableStream` `mode`: `"cors"`, `"no-cors"`, `"same-origin"` oder `"navigate"` `credentials`: `"omit"`, `"same-origin"` (Standard) oder `"include"` `cache`: z. B. `"default"`, `"no-store"`, `"reload"`, `"no-cache"`, `"force-cache"` `redirect`: `"follow"`, `"error"` oder `"manual"` `referrer`, `referrerPolicy`, `integrity`, `keepalive`, `priority` `signal`: `AbortSignal` zum Abbrechen der Anfrage `duplex`: `"half"`, Pflicht bei einem `ReadableStream` als Body

Rückgabewert

Typ

Request

Beschreibung

Ein neues Request-Objekt, das an fetch() übergeben oder mit der Cache-API verwendet werden kann.

Beispiele

Einfache GET-Anfrage erstellen und ausführen

const request = new Request('https://api.example.com/users/42', {
  headers: { Accept: 'application/json' }
});

console.log(request.method, request.url);

const response = await fetch(request);
const user = await response.json();
console.log(user.name);

GET https://api.example.com/users/42 Max Mustermann

POST-Anfrage mit JSON-Body und Abbruch nach Zeitlimit

const request = new Request('https://api.example.com/orders', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ productId: 7, quantity: 2 }),
  signal: AbortSignal.timeout(5000) // nach 5 s abbrechen
});

try {
  const response = await fetch(request);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log('Bestellung angelegt:', await response.json());
} catch (err) {
  console.error('Fehler:', err.name, err.message);
}

Bestellung angelegt: { id: 1001, status: 'offen' }

Bestehende Anfrage kopieren und Header ergänzen (z. B. im Service Worker)

self.addEventListener('fetch', (event) => {
  const original = event.request;
  if (!original.url.startsWith('https://api.example.com/')) return;

  const headers = new Headers(original.headers);
  headers.set('X-Client-Version', '2.4.0');

  // Neue Anfrage auf Basis der alten, mit geänderten Headern
  const modified = new Request(original, { headers });
  event.respondWith(fetch(modified));
});

Body nur einmal lesbar – clone() verwenden

const request = new Request('/api/log', {
  method: 'POST',
  body: 'Hallo Welt'
});

const copy = request.clone();
console.log(await request.text());
console.log(request.bodyUsed);
console.log(await copy.text());

Hallo Welt true Hallo Welt

// Wichtig · Fallstricke

GET/HEAD ohne Body: Gibst du bei GET oder HEAD einen body an, wirft der Konstruktor einen TypeError.
Body wird verbraucht: Wurde der Body eines Requests schon gelesen (bodyUsed === true), kann er weder an fetch() übergeben noch als input für einen neuen Request verwendet werden. Rufe vorher clone() auf.
Verbotene Header: Header wie Host, Cookie, Origin oder Content-Length ignoriert der Browser stillschweigend. Im Modus \"no-cors\" sind außerdem nur einfache CORS-Header und die Methoden GET, HEAD und POST erlaubt.
Credentials in der URL (z. B. https://user:pass@host/) führen zu einem TypeError. Nutze stattdessen einen Authorization-Header.
Sicherheit: credentials: \"include\" sendet Cookies auch an fremde Origins. Der Server muss dann Access-Control-Allow-Credentials: true und eine konkrete Origin statt * senden. Verwende diese Option nur bei vertrauenswürdigen Endpunkten.
Streams als Body: Ein ReadableStream als Body funktioniert nur zusammen mit duplex: \"half\" und wird noch nicht von allen Browsern unterstützt (Safari eingeschränkt).
Kompatibilität: Der Konstruktor ist in allen modernen Browsern, in Web Workern und in Node.js ab Version 18 (global, auf Basis von undici) verfügbar. Der Internet Explorer unterstützt ihn nicht.

Siehe auch

Request Request.prototype.clone() Headers Response AbortSignal Cache