API-warmers

Houd REST- en GraphQL-endpoints warm, met echte methodes, headers, cookies, bodies en configuratiematrices.

13 min leestijd

API's worden precies zo koud als webpagina's. Is een JSON-response duur om op te bouwen en wordt die gecachet bij je CDN of gateway, dan betaalt de eerste client na het verlopen dezelfde prijs als een websitebezoeker.

API-warmers lossen dat op. Ze worden apart van website-warmers beheerd, onder Account → API-warmers, en hebben hun eigen planlimieten.

Los van website-warmers

API-warmers zijn een aparte functie met een eigen recht. Ontbreekt de sectie of is die vergrendeld, dan bevat je plan ze niet — zie Plannen en limieten.

Wanneer je er een gebruikt

Situatie	Waarom een API-warmer helpt
Een headless winkel of site	Product-, voorraad- en content-JSON wordt bij elke pagina-render opgehaald. Die routes opwarmen houdt de hele frontend snel.
Een publieke developer-API	Populaire endpoints en documentatievoorbeelden blijven vlot, in plaats van traag voor wie als eerste aanroept.
Een backend-for-frontend-laag	Samengestelde endpoints die naar meerdere services uitwaaieren zijn duur om opnieuw op te bouwen. Die opwarmen beschermt mobiele en webclients.
Zware GraphQL-operaties	Meestal domineert een handvol queries het verkeer. Juist die operaties opwarmen doet veel meer dan één keer `/graphql` aanroepen.

Een API-warmer is niet nuttig voor endpoints die nooit gecachet worden, of die per gebruiker uniek zijn en dus geen gedeelde gecachete kopie hebben om te vullen.

Een API-warmer aanmaken

1
Verifieer de API-hostname
Endpoint-URL's moeten een geverifieerde hostname gebruiken, net als bij website-warmers. Zie Hostnameverificatie.
2
Geef de warmer een naam en laat hem inactief
Configureer eerst, activeer als je tevreden bent.
3
Voeg een of meer endpoints toe
Elk endpoint heeft een URL en een HTTP-methode, en optioneel een label, body en content type.
4
Voeg authenticatie toe als het endpoint die nodig heeft
Globale headers en cookies worden toegepast op elk request dat de warmer doet.
5
Breid eventueel uit met een configuratiematrix
Dek veel varianten — talen, tenants, ID's — zonder tientallen bijna identieke warmers te maken.
6
Stel tempo en intervallen in, en activeer
Zelfde idee als bij website-warmers: vaak genoeg opwarmen om je cache-TTL te verslaan, langzaam genoeg om geen schade te doen.

Endpoints

Elk endpoint in de warmer wordt afzonderlijk geconfigureerd:

Label: Een optionele leesbare naam, zodat een lange lijst endpoints leesbaar blijft.
URL: Het volledige endpointadres op een geverifieerde hostname. Mag padplaatshouders bevatten zoals {id} of :id in combinatie met een PATH-dimensie.
Methode: GET, POST en andere, afhankelijk van je plan. Plannen staan doorgaans standaard GET en HEAD toe, met meer methodes op hogere niveaus.
Protocol: REST of GRAPHQL. Kies je GraphQL, dan verschijnen de velden voor operatie en query.
Request body-template: De body die meegestuurd wordt, voor methodes die er een dragen. Vereist het recht op API-request bodies.
Content-Type: Het content type van de request body, doorgaans application/json.
Idempotent: Markeert het endpoint als veilig om twee keer aan te roepen, waarmee de koud/warm dubbele fetch die de verbetering meet aangaat. Zet dit alleen aan als twee keer aanroepen echt geen bijwerkingen heeft.
Ingeschakeld: Of dit specifieke endpoint meedoet in runs. Handig om er één tijdelijk uit te zetten zonder hem te verwijderen.

Wees voorzichtig met schrijfoperaties als idempotent markeren

Een dubbele fetch op een endpoint dat orders aanmaakt, e-mail verstuurt of kaarten belast, doet dat twee keer. Markeer een endpoint alleen als idempotent wanneer herhalen echt onschadelijk is.

Configuratiematrices

De meeste API's hebben varianten: hetzelfde endpoint aangeroepen per taal, per tenant, per valuta of per ID. Voor elk een warmer maken is niet te onderhouden.

Een configuratiematrix lost dat op. Je definieert dimensies met meerdere waarden, en Cache Rocket klapt het volledige cartesisch product uit naar afzonderlijke warm-requests.

Soort dimensie	Voegt waarden in bij	Voorbeeld
`QUERY`	De query string	`locale=en`, `locale=nl`, `locale=de`
`HEADER`	Een request header	`X-Tenant: acme`, `X-Tenant: globex`
`COOKIE`	Een cookie	`currency=EUR`, `currency=USD`
`PATH`	Een `{plaatshouder}` in de URL	`{id}` → `1`, `2`, `3`

Een uitgewerkt voorbeeld

text

Endpoint:  GET https://api.example.com/v1/products/{category}

Dimensies:
  PATH   category = shoes, bags, hats
  QUERY  locale   = en, nl

Klapt uit naar 6 warm-requests:
  /v1/products/shoes?locale=en
  /v1/products/shoes?locale=nl
  /v1/products/bags?locale=en
  /v1/products/bags?locale=nl
  /v1/products/hats?locale=en
  /v1/products/hats?locale=nl

Combinaties vermenigvuldigen snel

Het totaal aan requests is het product van het aantal waarden van elke dimensie. Drie dimensies van vijf waarden is 125 combinaties uit één endpoint. Het formulier toont een lopende teller en het maximum van je plan — houd die in de gaten terwijl je waarden toevoegt.

Ga je over het planmaximum, dan laat de warmer zich niet opslaan. Verminder waarden, splits over meerdere warmers, of upgrade.

Authenticatie

Globale request headers en cookies worden toegepast op elke variant die de warmer genereert. Daar hoort een Authorization-header of een sessiecookie.

Gebruikelijke auth-headers

text

Authorization: Bearer JOUW_LANGLEVENDE_TOKEN
X-Api-Key: JOUW_API_SLEUTEL

Warm de variant op die echte clients ook opvragen

Varieert je cache op Authorization, dan vul je met een service-token een cache-item dat op dat token gesleuteld is — en dat raakt geen enkele echte client. Voor gedeelde, cachebare responses: warm op zoals een gewone client het endpoint aanroept.

Tokens verlopen. Geeft een API-warmer plots 401 terug, controleer dan eerst een hard ingevoerd token.

GraphQL

GraphQL vraagt een eigen aanpak, omdat de prestaties afhangen van de specifieke operatie, niet van het endpointpad. Eén keer /graphql raken zegt niets; je drie zwaarste queries opwarmen zegt alles.

Zet het protocol van een endpoint op GraphQL en geef daarna:

GraphQL-operatie — of dit een query of een mutation is. Mutaties opwarmen is vrijwel nooit gepast.
GraphQL-query — het operatiedocument dat verstuurd wordt.
Variabelen — geef die mee via de request body-template, of als waarden van matrixdimensies om meerdere sets variabelen op te warmen.

Note

GraphQL-opwarming valt onder een eigen planrecht, bovenop API-warmers.

OpenAPI-import

Op ondersteunde plannen kun je endpoints direct importeren uit een OpenAPI 3-specificatie in plaats van ze te typen. Plak de URL van een JSON- of YAML-spec en klik op Importeren; gevonden endpoints worden aan de warmer toegevoegd, klaar om op te schonen en bij te stellen.

Tip

Import haalt alles binnen wat de spec beschrijft, inclusief schrijfoperaties. Bekijk de lijst zorgvuldig en zet alles uit dat niet volgens schema aangeroepen mag worden, vóór je activeert.

Limieten en planning

Max opwarmingen per minuut: Tempoplafond voor deze API-warmer, gelijk aan max URL's per minuut bij een website-warmer.
Request timeout: Hoe lang wachten op een response voordat je opgeeft.
Auto-startinterval: Hoe vaak een nieuwe opwarmronde begint, in seconden.
Enqueue-interval: Tempo van opnieuw ingepland werk binnen de cyclus.
Herschrijven naar HTTPS: http://-endpoint-URL's opwaarderen naar https://.
Opwarmschema: Piek- en dalvensters, zelfde JSON-formaat als bij website-warmers. Zie Geavanceerd opwarmen.

Je plan begrenst daarnaast het aantal API-warmers, endpoints per warmer en combinaties per warmer.

Veelvoorkomende problemen

Alles geeft 401 of 403 terug.: De auth-header of cookie ontbreekt, is verkeerd of verlopen. Langlevende tokens zijn de gebruikelijke oorzaak — controleer of het token nog geldig is en niet geroteerd is.
De warmer laat zich niet opslaan wegens te veel combinaties.: Je matrix klapt verder uit dan het planmaximum. Verminder dimensiewaarden, splits endpoints over meerdere warmers, of upgrade.
De methode die ik nodig heb staat niet in de lijst.: Plannen beperken welke HTTP-methodes zijn toegestaan. Lagere niveaus staan doorgaans alleen GET en HEAD toe.
Het opwarmen draait netjes, maar responses blijven traag voor echte clients.: Je vult vermoedelijk een andere cachevariant dan clients opvragen — vaak door een Authorization-header, een cookie, of een header waarop je CDN varieert. Vergelijk het exacte request van een echte client met wat de warmer stuurt.
Kan ik een endpoint opwarmen dat een kortlevend, ondertekend token vereist?: Niet betrouwbaar, omdat de warmer per run geen nieuwe ondertekening kan maken. Bied een cachebare, niet-geauthenticeerde variant aan, of gebruik een langlevend service-token waar dat veilig is.