De Google Workspace API's geven je programmatische toegang tot Gmail, Drive, Sheets, Agenda en meer. In dit artikel krijg je als beginner een helder overzicht van welke API's er zijn, hoe authenticatie werkt en hoe je je eerste API-aanroep voorbereidt.
Welke Workspace-API's zijn er
Vrijwel elke Workspace-app heeft een eigen REST-API. De Gmail API leest en verstuurt mail, de Drive API beheert bestanden en mappen, de Sheets API leest en schrijft spreadsheetdata, de Docs API bewerkt documenten en de Calendar API beheert afspraken. Voor beheerderstaken is er de Admin SDK, waarmee je gebruikers, groepen en apparaten programmatisch beheert.
Naast deze kern zijn er API's voor Forms, Chat, Meet, Slides, Keep en Tasks. Ze delen allemaal dezelfde authenticatiemechanismen en een vergelijkbare opbouw, dus zodra je er een begrijpt, vallen de andere snel op hun plek.
| API | Waarvoor | Typische taak |
|---|---|---|
| Gmail API | Mail lezen, sturen, labelen en doorzoeken | Automatisch een ontvangstbevestiging sturen |
| Drive API | Bestanden en mappen aanmaken, delen en beheren | Een rapport opslaan in een gedeelde map |
| Sheets API | Spreadsheetdata lezen en schrijven | Een rij toevoegen aan een logboek |
| Docs API | Documenten lezen en bewerken | Een offerte vullen vanuit een sjabloon |
| Calendar API | Afspraken en agenda's beheren | Een afspraak inplannen vanuit een formulier |
| Admin SDK | Gebruikers, groepen en apparaten beheren | Een nieuwe medewerker automatisch aanmaken |
REST en kant-en-klare clientbibliotheken
Alle Workspace-API's zijn REST-API's die je vanuit elke taal kunt aanroepen. Google levert clientbibliotheken voor onder andere Python, JavaScript, Java, PHP, Go, .NET en Ruby, die de authenticatie en aanroepen voor je vereenvoudigen.
Authenticatie: OAuth versus service-account
De grootste hobbel voor beginners is authenticatie. Er zijn twee hoofdroutes. OAuth2 gebruik je als een applicatie namens een ingelogde gebruiker handelt, bijvoorbeeld een app die de agenda van de gebruiker toont. De gebruiker geeft expliciet toestemming.
Een service-account gebruik je voor server-naar-serverkoppelingen zonder menselijke tussenkomst, bijvoorbeeld een nachtelijk script dat rapporten genereert. Met domain-wide delegation kan een service-account namens gebruikers in je domein handelen. Wees daar voorzichtig mee: een service-account met domeinbrede rechten kan veel, dus geef het alleen de scopes die het echt nodig heeft.
Je eerste API klaarzetten in Google Cloud
- Open de Google Cloud Console en maak een project aan.
- Ga naar API's en services en schakel de API in die je nodig hebt, bijvoorbeeld de Sheets API.
- Configureer het OAuth-toestemmingsscherm met de benodigde scopes.
- Maak inloggegevens aan: een OAuth-client-ID voor gebruikersdata of een service-account voor servertaken.
- Download het credentialbestand en bewaar het veilig buiten je codebase.
- Installeer de clientbibliotheek voor je taal en doe een eerste testaanroep.
Vraag alleen wat je nodig hebt
Vraag altijd de minimaal benodigde scopes aan. Een API-koppeling met te brede rechten is een onnodig beveiligingsrisico. Lees alleen wat je nodig hebt en schrijf alleen waar het echt moet.
Quota en limieten
Elke API kent gebruikslimieten, uitgedrukt in aanvragen per minuut en per dag. Voor de meeste toepassingen zijn de standaardquota ruim voldoende, maar bij grootschalig gebruik loop je er tegenaan. Plan daarom batchverwerking en respecteer de limieten.
Fouten en limieten begrijpen
Werken met API's betekent ook leren omgaan met foutmeldingen. De Workspace-API's geven gestandaardiseerde foutcodes terug die je vertellen wat er misging. Een 401 betekent dat je authenticatie niet klopt, een 403 dat je rechten tekortschieten en een 429 dat je te veel aanvragen in korte tijd hebt gedaan. Door deze codes te herkennen, los je problemen gericht op in plaats van blind te zoeken.
Vooral de 429-fout, die op een overschreden limiet wijst, verdient aandacht. De juiste reactie is niet om meteen opnieuw te proberen, want dat verergert het probleem. In plaats daarvan gebruik je exponentiële backoff: je wacht steeds langer voordat je het opnieuw probeert. De clientbibliotheken van Google bieden hiervoor vaak ingebouwde ondersteuning, zodat je het wiel niet zelf hoeft uit te vinden.
Houd ook rekening met de verschillen tussen API's. De Gmail API kent andere limieten dan de Sheets API, en sommige bewerkingen zijn zwaarder dan andere. Lees voor elke API die je gebruikt de pagina over quota en limieten, zodat je je verwachtingen en je code daarop afstemt. Een goed begrip van de grenzen voorkomt dat je applicatie op het slechtst mogelijke moment vastloopt op een limiet die je had kunnen zien aankomen.
Beginnen met je eerste aanroep
De snelste manier om te leren is de officiële API Explorer en de quickstart-gidsen van Google. Daarmee doe je een echte aanroep zonder eerst een complete applicatie te bouwen. Begin klein: lees bijvoorbeeld met de Sheets API een enkele cel uit, of haal met de Gmail API de lijst met labels op. Werkt dat, dan heb je je authenticatie correct opgezet en kun je verder bouwen.
Test eerst met een onschuldige aanroep
Kies voor je allereerste aanroep een leesbewerking die niets verandert, zoals het ophalen van een lijst of een enkele waarde. Zo controleer je je authenticatie en scopes zonder dat je per ongeluk data overschrijft of mail verstuurt.
Heb ik een betaald Cloud-account nodig?
Nee, de Workspace-API's zijn gratis te gebruiken binnen de quota. Je hebt wel een Google Cloud-project nodig, maar dat kost niets zolang je binnen de gratis limieten blijft.
Wat is het verschil tussen OAuth en een API-sleutel?
Een API-sleutel volstaat alleen voor publieke data zonder gebruikerscontext. Voor toegang tot persoonlijke Workspace-data heb je altijd OAuth of een service-account nodig.
Wanneer kies ik OAuth en wanneer een service-account?
Kies OAuth als je app handelt namens een ingelogde gebruiker die toestemming geeft. Kies een service-account voor automatische server-naar-serverkoppelingen zonder dat er iemand inlogt, zoals een nachtelijk script.
Welke taal kan ik het beste gebruiken?
Google levert bibliotheken voor Python, JavaScript, Java, PHP, Go, .NET en Ruby. Kies de taal waarin je team al werkt. Python en JavaScript hebben de meeste voorbeelden.
Hoe voorkom ik dat ik mijn quota overschrijd?
Gebruik batchverzoeken, cache resultaten waar mogelijk en bouw exponentiële backoff in bij foutmeldingen over limieten. Vraag bij structureel hoog gebruik een quotaverhoging aan.
Waar bewaar ik mijn credentials veilig?
Bewaar credentialbestanden en tokens nooit in je codebase of in versiebeheer. Gebruik omgevingsvariabelen of een secret manager, en geef elke koppeling alleen de scopes die ze echt nodig heeft.
Volgende stappen
Zodra je de basis beheerst, kun je API's combineren tot krachtige automatiseringen. Wil je liever geen code schrijven, dan koppelen tools als n8n, Make en Zapier dezelfde API's via een grafische interface. Voor maatwerk binnen Workspace zelf is Apps Script vaak het snelst. Beveilig je koppelingen goed met veilig tokenbeheer.