De meeste moderne webapps praten voortdurend met een server. De JavaScript Fetch API is de standaardmanier om dat te doen, en deze is ingebouwd in browsers en in Node.js 18 en hoger, dus u hoeft niets te installeren.

Voor het basisgebruik zijn er twee regels nodig, maar veel tutorials stoppen daar en laten het deel weg dat echte bugs veroorzaakt: het afhandelen van fouten. We hebben de voorbeelden in deze handleiding getest met een kleine lokale server op Node.js 24, en de getoonde uitvoer is afkomstig van die run. example.com in de code staat voor je eigen API. Als beloften nieuw voor je zijn, begin dan met JavaScript-beloften uitgelegd.

Wat is de Fetch-API?

Fetch is een op beloften gebaseerde interface voor het doen van HTTP-verzoeken. Het verving het oudere, callback-gestuurde XMLHttpRequest, en veel projecten gebruiken het nu in plaats van een bibliotheek toe te voegen voor eenvoudige oproepen.

Een GET-verzoek

Fetch maakt standaard een GET-verzoek. Er zijn twee stappen, en elke stap heeft await nodig: eerst komen de antwoordheaders binnen en dan lees je de hoofdtekst.

const response = await fetch("https://example.com/users/1");
const user = await response.json();

console.log(user);

// { id: 1, name: 'Asha' }

Deze twee stappen bestaan ​​omdat de hoofdtekst groot kan zijn en later arriveert dan de headers. In een browserscript heeft topniveau await een module nodig, dus u plaatst deze meestal in een async functie. Zie onze JavaScript async/await-handleiding.

Het Response-object

Voordat u de hoofdtekst leest, kunt u het antwoord bekijken:

console.log(response.status, response.ok, response.headers.get("content-type"));

// 200 true application/json

Een lichaam kan slechts één keer worden gelezen. Een tweede keer bellen naar json() mislukte in onze test:

await res.json();
await res.json();

// TypeError: Body is unusable: Body has already been read

Als u het toch twee keer wilt lezen, bel dan eerst response.clone().

De grote verrassing: een 404 gooit niet

Dit is het belangrijkste in dit artikel. We hebben een gebruiker gevraagd die niet bestaat:

const res = await fetch("https://example.com/users/999");
console.log(res.status, res.ok);

// 404 false

Er werd geen uitzondering gemaakt. Wat het ophalen betreft, werkte het verzoek: de server werd bereikt en antwoordde. De belofte wordt alleen verworpen als er helemaal geen bruikbaar antwoord komt, zoals bij een netwerkstoring. Dus code als deze heeft een verborgen bug:

try {
  const res = await fetch(url);
  const data = await res.json();   // may be an error payload
  showUser(data);                  // runs anyway for 404 and 500
} catch (error) {
  showError();                     // does not run for 404 or 500
}

Bekijk ons spiekbriefje voor HTTP-statuscodes om te zien wat elke code betekent.

Een herbruikbare hulp

Herhaal die controle niet overal. Wikkel het een keer:

async function getJson(url, options) {
  const response = await fetch(url, options);
  if (!response.ok) {
    throw new Error(`Request failed with status ${response.status}`);
  }
  return response.json();
}

try {
  await getJson("https://example.com/users/999");
} catch (error) {
  console.log("caught:", error.message);
}

// caught: Request failed with status 404

Nu komen HTTP-fouten en netwerkfouten beide in hetzelfde catch terecht. Deze kleine functie is de moeite waard in elk project. Een echte versie kan ook een foutmelding uit de antwoordtekst lezen en een 204 No Content antwoord afhandelen, dat geen JSON heeft om te parseren.

POST JSON-gegevens

Geef een optieobject door als tweede argument. Voor JSON moet je zelf twee dingen doen: de data omzetten naar een string en de header instellen.

const created = await getJson("https://example.com/users", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Ben" }),
});

console.log(created);

// { id: 2, name: 'Ben', type: 'application/json' }

Onze testserver echode het ontvangen inhoudstype terug en bevestigde dat de header was aangekomen. Het vergeten van die header is een veel voorkomende oorzaak van verwarrende serverfouten, omdat veel frameworks JSON alleen parseren wanneer deze wordt gedeclareerd. Om een ​​formulier of bestanden te uploaden, geeft u een FormData object door als hoofdtekst en stelt u niet Content-Type in, omdat de browser zelf een grenswaarde moet toevoegen.

Andere methoden en opties

Kiezen tussen REST en andere API-stijlen? Onze vergelijking van REST versus GraphQL laat zien hoe ophalen bij beide past.

Queryreeksen

Bouw geen queryreeksen door tekst samen te voegen, omdat speciale tekens deze kapot maken. URLSearchParams verzorgt de codering voor u:

const params = new URLSearchParams({ q: "red shoes", page: 2 });
console.log(params.toString());

// q=red+shoes&page=2

await getJson(`https://example.com/search?${params}`);

// { q: 'red shoes', page: '2' }

De server heeft red shoes correct ontvangen en de ruimte is hersteld.

Time-outs en annuleren

Fetch zal lang wachten op een trage server, tenzij je anders vertelt. AbortSignal.timeout() stelt een limiet. Ons testeindpunt duurde twee seconden, tegen een limiet van 200 milliseconden:

try {
  await fetch("https://example.com/slow", { signal: AbortSignal.timeout(200) });
} catch (error) {
  console.log(error.name);
}

// TimeoutError

Om handmatig te annuleren, bijvoorbeeld wanneer een gebruiker een pagina verlaat of een nieuwe zoekterm typt, gebruikt u een AbortController:

const controller = new AbortController();
const pending = fetch("https://example.com/slow", { signal: controller.signal });

controller.abort();

try {
  await pending;
} catch (error) {
  console.log(error.name);
}

// AbortError

Om meerdere verzoeken tegelijk uit te voeren, gebruikt u Promise.all, wat veel sneller is dan ze één voor één af te wachten:

const [user, search] = await Promise.all([
  getJson("https://example.com/users/1"),
  getJson("https://example.com/search?q=a&page=1"),
]);

Elke vorm van mislukking

Hier ziet u hoe elke mislukking er tijdens onze run uitzag, samen met hoe u ze van elkaar kunt onderscheiden:

Die laatste rij is gebruikelijk in de productie. Een proxy die een 502 retourneert, stuurt vaak een HTML-foutpagina. We reproduceerden dit en res.json() gooide een SyntaxError. Als u response.ok controleert voordat u gaat parseren, rapporteert u het echte probleem en niet een verwarrende parseerfout.

CORS en referenties

In een browser is een verzoek van de ene oorsprong naar de andere onderworpen aan CORS, de regels voor het delen van bronnen tussen verschillende bronnen. Als u een fout ziet waarin Access-Control-Allow-Origin wordt vermeld, hoort de oplossing op de server te staan, die uw site moet toestaan. In uw JavaScript wordt de fout alleen als generiek weergegeven TypeError, dus kijk naar de browserconsole voor de werkelijke reden. Node.js dwingt CORS niet af, dus een verzoek dat in een script werkt, kan nog steeds mislukken in de browser.

Standaard verzenden browsers geen cookies bij cross-origin-verzoeken. Stel credentials: "include" in als u ze nodig heeft, en zorg ervoor dat de server dit toestaat. Plaats nooit geheime API-sleutels in browser-JavaScript, aangezien iedereen ze kan lezen. Bewaar ze op uw server.

Veel voorkomende fouten

• Niet gecontroleerd response.ok. Foutreacties worden als succesvol beschouwd.
• Het tweede await vergeten. response.json() levert ook een belofte op.
• Vergeten JSON.stringify. Een object doorgeven zoals het lichaam verzendt [object Object].
• Instelling Content-Type met FormData. Dit doorbreekt de grens, dus laat deze weg.
• Er is geen time-out. Een vastgelopen verzoek kan de spinner van een pagina voor onbepaalde tijd laten draaien.
• JSON wordt geparseerd voor een leeg antwoord. Een 204 heeft geen hoofdtekst en json() zal gooien.

Tot slot

Fetch is eenvoudig als je eenmaal de hoofdregel onthoudt: een reactie is niet hetzelfde als een succes. Kopieer de kleine helper naar uw project, voeg een time-out toe en test uw foutpaden. Bouw als volgende stap een kleine pagina die gegevens uit een API laadt, een duidelijke foutmelding weergeeft en de gebruiker een langzame zoekopdracht laat annuleren.

Veelgestelde vragen

Blijf leren