# ETags gebruiken voor efficiente API-caching

[[TOC]]

Steeds dezelfde data ophalen die niet veranderd is, is verspilling van bandbreedte, tijd en soms quota. ETags lossen dit elegant op: de API vertelt je of er iets veranderd is voordat je de hele resource downloadt. Voor integraties die vaak dezelfde data raadplegen, levert dit forse winst op. In dit artikel leer je ETags inzetten voor caching en voor veilig schrijven.

## Wat een ETag is

Een ETag is een korte vingerafdruk van de huidige versie van een resource. Verandert de resource, dan verandert de ETag.

- De API geeft de ETag mee in de response, vaak in de `ETag`-header of in een `etag`-veld in de JSON.
- Jij bewaart de ETag samen met de gecachte data.
- Bij een volgende call stuur je de ETag mee als voorwaarde.
- De API antwoordt alleen met de volledige data als die veranderd is.

:::info title="Wat zijn conditionele requests?"
Het idee heet conditionele requests. In plaats van te vragen geef mij de data, vraag je geef mij de data alleen als die anders is dan wat ik al heb. Dat bespaart een volledige download wanneer er niets gewijzigd is.
:::

## Caching met If-None-Match

Voor efficient lezen gebruik je de `If-None-Match`-header met je opgeslagen ETag.

:::howto title="Conditioneel lezen met ETags"
1. Doe een eerste call en bewaar de resource samen met de ETag uit de response.
2. Stuur bij de volgende call die ETag mee in de `If-None-Match`-header.
3. Krijg je een **304 Not Modified**? Gebruik je gecachte kopie, er is niets veranderd.
4. Krijg je een **200** met nieuwe data? Vervang je cache en bewaar de nieuwe ETag.
:::

Een ruw voorbeeld van de tweede call ziet er zo uit:

```http
GET /admin/directory/v1/groups/sales@example.com HTTP/1.1
Host: admin.googleapis.com
Authorization: Bearer ya29...
If-None-Match: "abc123etagwaarde"
```

Bij een ongewijzigde resource antwoordt de server met `304 Not Modified` en een lege body, zodat je je gecachte versie hergebruikt.

:::tip title="304 is bijna gratis"
Een 304-respons bevat geen body en is dus heel licht. Voor vaak geraadpleegde maar zelden veranderende data, zoals organisatie-eenheden of groepsinstellingen, bespaart deze aanpak veel dataverkeer en versnelt het je integratie merkbaar.
:::

## Veilig schrijven met If-Match

ETags voorkomen ook dat je per ongeluk andermans wijziging overschrijft. Dit heet optimistic concurrency.

:::howto title="Veilig schrijven met If-Match"
1. Lees de resource en onthoud de ETag.
2. Bereid je wijziging voor op basis van die versie.
3. Stuur de update met de ETag in de `If-Match`-header.
4. Is de resource ondertussen gewijzigd? Dan weigert de API met een **412 Precondition Failed** of een vergelijkbare conflictstatus.
5. Herlees de actuele versie en pas je wijziging opnieuw toe op die verse versie.
:::

:::warn title="Forceer een conflict nooit weg"
Negeer een conflict-respons nooit door simpelweg te forceren. Een conflict betekent dat iemand anders de resource heeft gewijzigd sinds jij hem las. Forceer je je versie eroverheen, dan wis je hun wijziging. Herlees altijd en voeg je wijziging op de verse versie toe.
:::

## Waar ETags wel en niet helpen

| Situatie | Aanpak |
| --- | --- |
| Je raadpleegt dezelfde, zelden veranderende resource vaak | ETags besparen veel; gebruik `If-None-Match`. |
| Je verwerkt elke keer compleet nieuwe data | ETags helpen weinig; er valt niets te hergebruiken. |
| Je doet gelijktijdige updates op dezelfde resource | Gebruik `If-Match` om verlies van wijzigingen te voorkomen. |

## Praktische aandachtspunten

- **Bewaar de ETag exact**, inclusief de aanhalingstekens die de server meestuurt. Strip ze niet, anders matcht je conditionele request niet.
- **Niet elke API zet de ETag op dezelfde plek.** Sommige Workspace-API's geven hem in de HTTP-`ETag`-header, andere in een `etag`-veld in de JSON-body. Controleer de documentatie van de specifieke API.
- **Verloopt een ETag, vernieuw dan je cache.** Krijg je een 200 met nieuwe data, dan vervang je zowel de inhoud als de bewaarde ETag.

:::faq
### Ondersteunen alle Workspace-API's ETags?
Veel API's wel, maar niet alle, en de plek waar de ETag staat verschilt per API. Controleer in de documentatie of conditionele requests ondersteund worden en of de ETag in een header of in een JSON-veld staat.

### Bespaart een 304 ook quota?
Een 304 bespaart vooral bandbreedte en tijd. Of het ook meetelt voor je quota verschilt per API, maar het is hoe dan ook efficienter dan telkens de volledige resource ophalen.

### Hoe lang is een ETag geldig?
Een ETag blijft geldig zolang de resource niet wijzigt. Verandert de resource, dan krijg je vanzelf een nieuwe versie met een nieuwe ETag terug en vervang je je gecachte waarde.

### Wat als ik geen ETag bewaar?
Dan val je terug op gewone, onvoorwaardelijke requests die altijd de volledige data ophalen. Dat werkt prima, maar je mist de efficientiewinst van conditionele requests.

### Welke statuscode krijg ik bij een schrijfconflict?
Meestal een **412 Precondition Failed** wanneer je `If-Match`-voorwaarde niet meer klopt. Herlees dan de resource, neem de nieuwe ETag over en probeer je wijziging opnieuw.

### Moet ik de ETag zelf berekenen?
Nee. De server bepaalt en levert de ETag. Jij bewaart hem alleen en stuurt hem ongewijzigd terug in `If-None-Match` of `If-Match`.
:::

Met ETags maak je je integratie zuiniger en veiliger: minder onnodig dataverkeer en bescherming tegen het overschrijven van wijzigingen.