Een externe API aanroepen vanuit Apps Script

Een externe API aanroepen vanuit Apps Script opent de deur naar elke dienst met een REST-API. Je koppelt Workspace aan betaalproviders, CRM-systemen, AI-modellen of je eigen backend. In dit artikel leer je GET- en POST-requests sturen met UrlFetchApp, authenticatie toevoegen, de respons verwerken en fouten netjes afvangen.

De basis: UrlFetchApp

Alle HTTP-verkeer naar buiten loopt via UrlFetchApp.fetch(). In de eenvoudigste vorm geef je alleen een URL mee en krijg je een respons-object terug:

function haalData() {
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/status');
  const tekst = response.getContentText();
  const data = JSON.parse(tekst);
  Logger.log('Status: ' + data.status);
}

getContentText() geeft de body als string, die je met JSON.parse() omzet naar een bruikbaar object.

Een POST-request met JSON

Voor het versturen van data gebruik je een POST met een JSON-payload:

function stuurData() {
  const payload = { naam: 'Patrick', actie: 'registreer' };
  const opties = {
    method: 'post',
    contentType: 'application/json',
    payload: JSON.stringify(payload)
  };
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/registreer', opties);
  Logger.log(response.getResponseCode());
}

Let op: payload moet een string zijn bij JSON, dus gebruik altijd JSON.stringify(). Voor de andere HTTP-werkwoorden zet je method op get, post, put, patch of delete.

Authenticatie met een API-sleutel

De meeste API's vereisen authenticatie via een header, vaak een Bearer-token of een API-sleutel. Bewaar die sleutel veilig in de Script Properties:

function authRequest() {
  const sleutel = PropertiesService.getScriptProperties().getProperty('API_KEY');
  const opties = {
    method: 'get',
    headers: {
      'Authorization': 'Bearer ' + sleutel
    }
  };
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/profiel', opties);
  return JSON.parse(response.getContentText());
}

Fouten netjes afvangen

Standaard gooit fetch() een uitzondering bij een foutcode zoals 404 of 500, waardoor je script stopt. Met muteHttpExceptions: true krijg je de respons toch terug en kun je zelf op de statuscode reageren:

function veiligeFetch() {
  const opties = { method: 'get', muteHttpExceptions: true };
  const response = UrlFetchApp.fetch('https://api.voorbeeld.nl/data', opties);
  const code = response.getResponseCode();

  if (code === 200) {
    return JSON.parse(response.getContentText());
  }
  Logger.log('Fout ' + code + ': ' + response.getContentText());
  return null;
}

De vier stappen op een rij

Elke API-koppeling volgt hetzelfde patroon:

1. URL bepalen: kies het juiste endpoint van de externe API.
2. Opties bouwen: stel method, headers en payload in.
3. Aanroepen: roep UrlFetchApp.fetch() aan met muteHttpExceptions: true.
4. Verwerken: controleer de responscode en parse de JSON-respons.

Meerdere requests tegelijk

Moet je tientallen aanroepen doen, bijvoorbeeld een rij in een spreadsheet per regel verrijken, dan is een loop met losse fetch-aanroepen traag. Met UrlFetchApp.fetchAll() voer je een lijst requests parallel uit:

function batchRequests() {
  const requests = [
    { url: 'https://api.voorbeeld.nl/a', muteHttpExceptions: true },
    { url: 'https://api.voorbeeld.nl/b', muteHttpExceptions: true }
  ];
  const responses = UrlFetchApp.fetchAll(requests);
  return responses.map(r => r.getResponseCode());
}

Let op het dagelijkse quotum voor UrlFetchApp-aanroepen op je accounttype en de time-out van standaard 360 seconden per aanroep.

Volgende stap

Met UrlFetchApp koppel je Workspace aan de buitenwereld. Wil je juist data ontvangen van externe systemen, lees dan webhooks ontvangen en verwerken. Voor het veilig en onderhoudbaar houden van dit soort koppelingen, zie best practices.