GraphQL persisted queries gebruiken voor snellere CDN-caching

Je content-API werkt prima in ontwikkeling, maar bij echt verkeer merk je dat elke paginalading de originserver van ContentGrid bereikt. GraphQL-queries die als POST-verzoeken worden verstuurd, omzeilen CDN-caches volledig. Persisted queries zetten deze verzoeken om naar GET-verzoeken met een stabiele URL, zodat Vercel Edge Cache of Cloudflare ze kan serveren zonder de origin te raadplegen bij herhaalde verzoeken.

Hoe persisted queries werken

In plaats van bij elk verzoek de volledige GraphQL-querystring mee te sturen, registreer je de query eenmalig bij ContentGrid en ontvang je een hash terug. Toekomstige verzoeken sturen alleen de hash als GET-parameter. ContentGrid zoekt de hash op, voert de query uit en geeft het resultaat terug. Omdat de URL stabiel is en de methode GET is, cachen CDN's de response zoals elk statisch bestand.

• Queryregistratie gebeurt eenmalig, doorgaans tijdens de build of in een setupscript.
• De hash is deterministisch — dezelfde query produceert altijd dezelfde hash.
• Variabelen (zoals een entry-slug) worden nog steeds als GET-parameters meegegeven.
• De CDN-cachesleutel is de hash plus de variabelen.

Queries registreren in ContentGrid

Gebruik de ContentGrid Management API of CLI om je queries vóór deployment te registreren:

• Schrijf je queries in .graphql-bestanden in een queries/-map.
• Voer contentgrid queries push --dir queries/ uit om alle queries te registreren.
• De CLI print de hash voor elke query — sla deze op in een query-hashes.json-bestand.
• Voeg de push-opdracht toe aan je CI-pipeline vóór de buildstap.

Voeg query-hashes.json toe aan je repository zodat front-endcode hashes kan importeren zonder de API te raadplegen tijdens runtime.

Persisted queries aanroepen vanuit Next.js

Vervang in je data-fetchingcode standaard GraphQL POST-aanroepen door GET-aanroepen met de hash:

• Importeer de hash uit query-hashes.json.
• Bouw de URL op: https://cdn.contentgrid.io/graphql?queryHash=HASH&variables=JSON.
• Gebruik fetch met next: { revalidate: 60 } voor ISR, of cache: 'force-cache' voor volledig statische content.
• Vercel's CDN cachet de GET-response op de edge automatisch.

Cache-TTL's instellen

Verschillende contenttypes hebben verschillende cacheduur nodig. Een homepage-hero moet binnen minuten na een contentwijziging worden bijgewerkt. Een blogarchiefpagina mag een uur verouderd zijn. Stel per query de cache-headers in:

• ContentGrid laat je queries annoteren met een standaard-TTL bij registratie.
• Overschrijf de TTL per verzoek via de Cache-Control-header die je fetch retourneert.
• Gebruik ContentGrid-webhooks om Vercel-revalidatie te triggeren bij het publiceren van content — zo houd je TTL's lang terwijl wijzigingen snel doorkomen.

Persisted queries gecombineerd met webhook-gedreven revalidatie geven je de prestaties van een statische site met de flexibiliteit van live content. De meeste teams zien een vermindering van 60–80% in origin-verzoeken na deze instelling, wat bij hogere verkeersvolumes ook de ContentGrid API-gebruikskosten verlaagt.