JavaScript/WindowOrWorkerGlobalScope/fetch

Aus SELFHTML-Wiki
Wechseln zu: Navigation, Suche
Browserunterstützung
caniuse.com

Das Fetch-API stellt mit der globalen Funktion fetch eine moderne, auf Promises basierende Alternative zu XMLHttpRequest dar, um mittels HTTP-Zugriffen Daten von anderswo holen (engl.: fetch) zu können.[1][2]

Wenn Dir das HTTP-Protokoll nicht bekannt ist, empfehlen wir Dir unser kurzes Einsteiger-Tutorial.

Fetch zerlegt den Ablauf eines HTTP-Requests in mehrere Schritte und abstrahiert die Funktionseinheiten von HTTP als JavaScript-Objekte. Das macht den Zugriff besser steuerbar. Um der asynchronen Natur von HTTP-Requests gerecht zu werden, ist Fetch vollständig auf Promises aufgebaut. Mit Hilfe von await ist es so auch möglich, die mit XMLHttpRequest erforderliche Event-Interaktion und damit die Inversion of Control[3] zu vermeiden.

Das Fetch-API wurde von der WHATWG eigenständig spezifiziert[4] und steht auf dem window-Objekt, in Web_Workern und seit Version 21 endlich auch nichtexperimentell in node.js zur Verfügung. Die grundlegenden Interfaces, auf denen das Fetch-API aufbaut, ist die fetch-Methode selbst sowie die die Interfaces Headers, Request und Response. Konzepte wie CORS werden automatisch behandelt.

Themen

  • Überblick
    • Einführungsbeispiel: Abrufen eines JSON-codierten Objekts
     
  • Daten empfangen
    • Auf HTTP-Status reagieren
    • Response-Datenstrom lesen
     
  • Daten senden
    • Request-Methode auf POST setzen
    • Bereitstellen eines Request-Body
    • Unterschiedliche Formate
    • Request-Objekte im Selbstbau
     
  • Header
    • Request-Header setzen
    • Response-Header auslesen
     
  • Abbruch!
    • Ein Abortsignal bereitstellen
    • Request abbrechen
     
  • Auf fremde Server zugreifen
    • CORS Header
    • Risiken und Nebenwirkungen
     


Überblick

Request- und Response-Objekte kann man direkt mit den jeweiligen Konstruktoren erzeugen, aber das ist nur in Ausnahmefällen notwendig. Normalerweise erzeugt fetch() das Request-Objekt selbst und liefert ein Response Objekt zurück.

Um einen Request zum Laden einer Ressource zu starten, verwendet man die fetch()-Methode. Sie benötigt mindestens ein Argument: entweder einen String, der die URL für die Ressource enthält, die beschafft werden soll, oder ein fertiges Request-Objekt. Für Requests, die über einen Standard-GET hinausgehen, kann als zweites Argument ein RequestInit-Objekt übergeben werden. Dabei handelt es sich um ein einfaches Objekt ohne Konstruktor, dass Du beispielsweise über ein Objektliteral erzeugen kannst und dessen Eigenschaften die diversen Fetch-Optionen enthalten.

Zurückgegeben wird ein Promise, das nach Erhalt des HTTP-Headers der Serverantwort erfüllt wird und den HTTP-Teil der Serverantwort in Form eines Response-Objekts bereitstellt. Ein möglicher Content-Teil der HTTP-Antwort wird separat behandelt. Wenn der Server nicht antwortet, die URL oder das RequestInit-Objekt Fehler enthält oder der Request blockiert wurde, wird das Promise sofort oder später mit einem TypeError zurückgewiesen.

Sobald die Response zur Verfügung steht, gibt es mehrere Eigenschaften und Methoden, um sie weiterzuverarbeiten. Die Methoden, die den Response-Body auslesen, liefern ihrerseits wieder ein Promise zurück, sodass ein typischer fetch-Aufruf aus zwei .then() Schritten besteht.

Basis-fetch mit HTTP GET

Wir zeigen hier einen grundlegenden GET-Request mit fetch. Die Funktion updateWetterdaten soll zu einer Wetterstation, deren ID sie als Argument erhält, die aktuellen Werte ermitteln und anzeigen. Das Beispiel setzt voraus, dass der Server die Daten als JSON-codiertes Objekt zurückgibt. Die Anzeige selbst ist nicht Teil des Beispiels und wird durch die Funktion showData() symbolisiert.

Die Verteilung der Meldung auf zwei Zeilen bei new Error() ist der Lesbarkeit im Wiki geschuldet.

Typischer fetch-Ablauf mit await 
async function getJsonData(url) {
   const response = await fetch(url);
   if (response.ok)
      return response.json();
   else
      throw new Error(`Wetterdaten konnten nicht geladen werden, ` + 
                      `HTTP-Status ${response.status}`);
  }
}

async function updateWetterdaten(station) {
   try {
      const url = new URL("https://weather.example.com/getData.php");
      url.searchParams.set("station", station);

      const wetter = await getJsonData(url);
      showData(station, wetter);
   }
   catch (fehler) {
      showError(station, fehler);
   }
}

Wir hätten den URL-Parameter natürlich auch direkt in den URL-String einsetzen können, aber das URLSearchParams-Objekt zu verwenden ist besser - allein schon deshalb, weil es automatisch für die URL-kompatible Maskierung sucht falls jemand eine Station wie "R&D" übergibt.

Ohne await geht es auch, dann müssen einige Callbacks erstellt werden. Wir empfehlen aber, wann immer möglich mit await zu arbeiten, das ist deutlich besser lesbar.

Typischer fetch-Ablauf mit .then/.catch 
function getJsonData(url) {
   return fetch(url)
      .then(response => {
         if (response.ok)
            return response.json();
         else
            throw new Error(`Wetterdaten konnten nicht geladen werden, ` +
                            `HTTP-Status ${response.status}`);
      });
}

function updateWetterdaten(station) {
   const url = new URL("https://weather.example.com/getData.php");
   url.searchParams.set("station", station);

   getJsonData(url)
     .then(wetter => showData(station, wetter))
     .catch(fehler => showError(station, fehler));
}

Verwandte APIs

Für die Funktion von Fetch werden einige andere Browser-APIs genutzt.

Promise

Das Promise-API dient zur Steuerung und Koordination asynchroner Abläufe und ersetzt „Einmal-Events“

DOM (AbortController/AbortSignal)

Um einen fetch-Ablauf abbrechen zu können, lässt sich im RequestInit-Objekt ein Abortsignal mitgeben.

Streams (ReadableStream)

Um Daten für einen Request oder aus einer Response als Stream bereitstellen bzw. auslesen zu können. Dies ist für große Datenmengen interessant, weil man so unnötige Kopien vermeiden kann.

Informationen zum Streams API unter Streams API bei Mozilla

File (Blob und File)

Daten für einen Request oder aus einer Response können als Blob- oder File-Objekt bereitgestellt oder erhalten werden

URL (UrlSearchParams)

Ein URLSearchParams Objekt kann als Request-Body übergeben werden und wird dann mit MIME-Typ application/x-www-form-urlencoded übertragen

XMLHttpRequest (FormData)

Ein FormData-Objekt (das für XMLHttpRequest erfunden wurde) kann für einem Request bereitgestellt werden, und eine Response kann als FormData-Objekt empfangen werden. Der Absender kann die Daten dafür application/x-www-form-urlencoded oder multipart/form-data bereitstellen.

ArrayBuffer, TypedArray und DataView

Request- und Response-Body können in Form dieser ECMAScript-Standardobjekte bereitgestellt werden. Der Empfang ist als UInt8Array möglich.

Data

Interfaces (wird obsolet)

Die folgenden Abschnitte werden noch in eigene SELF-Wiki-Artikel ausgelagert und stellen zur Zeit einen Stub dar.

WindowOrWorkerGlobalScope

WindowOrWorkerGlobalScope (früher GlobalFetch genannt) ist ein Mixin des Fetch API, das von den Window und WorkerGlobalScope Interfaces implementiert wird. fetch()-Aufrufe stehen damit sowohl für den JavaScript GUI Thread als auch für Web Worker zur Verfügung.

  • WindowOrWorkerGlobalScope.fetch()

Headers

Ein Headers-Objekt kann man über die headers-Eigenschaft von Request- oder Response-Objekten des Fetch API erhalten, oder über die Headers() Konstruktorfunktion erzeugen.

Ein Headers-Objekt verfügt über eine Guard-Eigenschaft. Als Anwender kann man diese Eigenschaft weder lesen noch ändern, aber sie beeinflusst, welche Header man setzen darf. Festgelegt wird sie beim Erzeugen des Headers-Objekts.

Erzeugt Guard Erlaubte Header
Headers Konstruktor none alle
Request Konstruktor request alle, bis auf verbotene Request-Header
Request Konstruktor mit mode=no-cors request nur die Header der CORS Safelist (simple headers)
Response Konstruktor response alle, bis auf verbotene Response-Header
error() oder redirect() Methoden immutable keine. Änderungsversuche mit set(), append() oder delete() werfen einen TypeError

Listen der verbotenen bzw. CORS-Safelisted Header finden sich in der Fetch Spezifikation.

Constructor

  • Headers()

Methoden

  • Headers.append()
  • Headers.delete()
  • Headers.get()
  • Headers.getAll()
  • Headers.has()
  • Headers.set()

Request

Anforderung von Daten

Constructor

  • Request()

Eigenschaften

  • Body.bodyUsed
  • Request.cache
  • Request.context
  • Request.credentials
  • Request.headers
  • Request.method
  • Request.mode
  • Request.referrer
  • Request.url

Methoden

  • Body.arrayBuffer()
  • Body.blob()
  • Request.clone()
  • Body.formData()
  • Body.json()
  • Body.text()

Response

Antworten

Constructor

  • Response()

Eigenschaften

  • Body.bodyUsed
  • Response.headers
  • Response.ok
  • Response.status
  • Response.statusText
  • Response.type
  • Response.url
  • Response.useFinalURL

Methoden

  • Body.arrayBuffer()
  • Body.blob()
  • Response.clone()
  • Response.error()
  • Body.formData()
  • Body.json()
  • Response.redirect()
  • Body.text()
  • Daten mit JS nachladen
    • AJaX
    • Fetch API
     

Weblinks

  1. ↑ MDN: Fetch API
  2. ↑ Jake Archibald: That's so fetch!
  3. ↑ Wikipedia: Inversion of Control, abgerufen am 31.08.2026
  4. ↑ WHATWG: Fetch method, abgerufen am 31.08.2026

Abgerufen am 4.09.2026
von "http://wiki.selfhtml.org/wiki/JavaScript/WindowOrWorkerGlobalScope/fetch"