# Workspace API OpenAPI-specificaties gebruiken

[[TOC]]

Handmatig API-clients schrijven is foutgevoelig en saai. Waarom zou je elke endpoint, parameter en datastructuur met de hand overtikken als de API zichzelf al beschrijft? Workspace-API's publiceren een machine-leesbare definitie waaruit je clients, mock-servers en documentatie automatisch genereert. In dit artikel leer je deze specificaties benutten.

## Discovery-documenten en OpenAPI

Google beschrijft zijn API's met discovery-documenten: een JSON-formaat dat alle endpoints, methoden, parameters en schema's bevat. Dit is Google's eigen variant. De bredere industriestandaard heet OpenAPI.

- Een **discovery-document** is Google's machine-leesbare API-beschrijving.
- **OpenAPI** is de wijdverbreide standaard waar veel tools omheen gebouwd zijn.
- Je kunt discovery omzetten naar OpenAPI om die brede toolketen te benutten.

Het overzicht van alle Google-API's en hun discovery-URL's begint bij het root-document op `https://discovery.googleapis.com/discovery/v1/apis`. Dat bestand vermeldt per API (zoals Gmail, Drive of Calendar) de eigen `discoveryRestUrl`, die je vervolgens ophaalt voor de volledige beschrijving van die ene API.

:::info title="Je gebruikt de specs al indirect"
De officiele Google-clientbibliotheken worden zelf gegenereerd uit deze discovery-documenten. Daarom zijn de methodenamen zo voorspelbaar: ze spiegelen direct de API-definitie. Je profiteert dus al van deze specificaties, ook als je ze niet zelf gebruikt.
:::

## Wat je eruit genereert

Met een OpenAPI-specificatie in handen open je een hele gereedschapskist:

- **Clients:** genereer type-veilige clientcode in vrijwel elke taal met tools zoals `openapi-generator`, in plaats van calls met de hand te schrijven.
- **Mocks:** draai een mock-server die de API nabootst, zodat je tegen voorspelbare antwoorden test zonder echte calls te doen.
- **Documentatie:** genereer doorzoekbare, interactieve documentatie waarin teamleden de endpoints kunnen verkennen.

## Een client genereren

:::howto title="Zo genereer je een client"
1. Haal het discovery-document van de gewenste API op via de `discoveryRestUrl` uit het root-document.
2. Zet het zo nodig om naar een OpenAPI-specificatie met een conversietool, bijvoorbeeld `google-discovery-to-swagger` of `google-discovery-to-openapi`.
3. Draai `openapi-generator` met je doeltaal en de specificatie als invoer.
4. Integreer de gegenereerde client in je project en authenticeer zoals gebruikelijk met OAuth of een service-account.
5. Hergenereer wanneer de API-definitie wijzigt om synchroon te blijven.
:::

:::tip title="Pin de versie van je spec"
Pin de versie van de specificatie die je gebruikt, net als bij je dependencies. Zo genereer je reproduceerbaar dezelfde client en voorkom je dat een onverwachte wijziging in de API-definitie stilletjes je gegenereerde code verandert. Behandel de spec als onderdeel van je build, bijvoorbeeld door het gedownloade document in je repository te committen.
:::

## Mocks voor betrouwbare tests

Tegen de echte Workspace-API testen is traag, verbruikt quota en raakt echte data. Een mock-server uit de specificatie lost dit op:

1. Voed je OpenAPI-specificatie aan een mock-server-tool, zoals Prism of WireMock.
2. De tool genereert antwoorden op basis van de schema's in de spec.
3. Je tests draaien tegen de mock in plaats van de echte API.
4. Je test daardoor sneller, zonder quota en zonder echte data te raken.
5. Voor end-to-end-tests draai je een beperkte set tegen de echte API.

:::warn title="Een mock is geen echte API"
Een mock weerspiegelt de specificatie, niet het echte gedrag van de API. Edge-cases, rate limits en subtiele validaties zitten er niet altijd in. Gebruik mocks voor snelle ontwikkeltests, maar bevestig kritiek gedrag altijd met een aantal tests tegen de echte API.
:::

## Veelgestelde vragen

:::faq
### Waar vind ik het discovery-document van een API?
Begin bij het root-document op `https://discovery.googleapis.com/discovery/v1/apis`. Daarin staat per API een `discoveryRestUrl` die naar het volledige JSON-document van die API verwijst. De directe URL staat meestal ook in de API-documentatie zelf.

### Is een gegenereerde client beter dan de officiele bibliotheek?
De officiele bibliotheken zijn meestal de beste keuze, want ze regelen authenticatie, paginering en backoff voor je. Genereer alleen zelf als je een taal of opzet gebruikt die niet officieel ondersteund wordt.

### Hoe blijf ik synchroon met API-wijzigingen?
Hergenereer periodiek uit een geversioneerde specificatie en draai je tests. Zo merk je breaking changes vroeg in plaats van pas in productie. Een geautomatiseerde stap in je CI die de spec ophaalt en met de vorige versie vergelijkt, helpt hierbij.

### Ondersteunen alle Workspace-API's discovery?
De meeste REST-API's wel. Controleer per API of er een discovery-document of een OpenAPI-specificatie beschikbaar is. Sommige nieuwere of gRPC-gebaseerde diensten leveren geen discovery-document.

### Welke tools converteren discovery naar OpenAPI?
Veelgebruikte open-source opties zijn `google-discovery-to-swagger` (APIs-guru) en `google-discovery-to-openapi`. Ze mappen de discovery-velden naar een geldige OpenAPI 3.x-spec die je daarna aan `openapi-generator` voert.
:::

Met API-specificaties als basis genereer je clients, mocks en documentatie automatisch, waardoor je integraties type-veilig, testbaar en synchroon met de echte API blijven.