Persisted Queries
Gebruik GraphQL-queries om vooraf gedefinieerde endpoints te maken zoals in REST, en profiteer van de voordelen van beide API's.
Beschrijving
Met REST maak je meerdere endpoints aan, elk met een vooraf gedefinieerde set gegevens.
| Voordelen | Nadelen |
|---|---|
| ✅ Het is eenvoudig | ❌ Het is tijdrovend om alle endpoints aan te maken |
✅ Toegankelijk via GET of POST | ❌ Een project kan te maken krijgen met knelpunten terwijl er gewacht wordt op endpoints |
| ✅ Kan gecached worden op de server of CDN | ❌ Documentatie is verplicht |
| ✅ Het is veilig: alleen bedoelde gegevens worden blootgesteld | ❌ Het kan traag zijn (met name voor mobiele apps), omdat de applicatie mogelijk meerdere verzoeken nodig heeft om alle gegevens op te halen |
Met GraphQL stuur je elke query naar één endpoint, dat precies de gevraagde gegevens teruggeeft.
| Voordelen | Nadelen |
|---|---|
| ✅ Geen onder- of overfetching van gegevens | ❌ Alleen toegankelijk via POST |
| ✅ Het kan snel zijn, omdat alle gegevens in één verzoek worden opgehaald | ❌ Het kan niet gecached worden op de server of CDN, waardoor het langzamer en duurder is dan het zou kunnen zijn |
| ✅ Het maakt snelle iteratie van het project mogelijk | ❌ Het kan vereisen dat je het wiel opnieuw uitvindt, zoals bij het uploaden van bestanden of caching |
| ✅ Het kan zichzelf documenteren | ❌ Je moet omgaan met extra complexiteiten, zoals het N+1-probleem |
| ✅ Het biedt een editor voor de query (GraphiQL) die de taak vereenvoudigt |
Persisted queries combineren deze 2 benaderingen:
- Ze gebruiken GraphQL om queries te maken en op te lossen
- Maar in plaats van één endpoint bloot te stellen, wordt elke vooraf gedefinieerde query onder zijn eigen endpoint beschikbaar gemaakt
Zo krijgen we meerdere endpoints met vooraf gedefinieerde gegevens, zoals bij REST, maar aangemaakt met GraphQL, waarbij we de voordelen van beide benutten en hun nadelen vermijden:
| Voordelen | Nadelen |
|---|---|
✅ Toegankelijk via GET of POST | |
| ✅ Kan gecached worden op de server of CDN | |
| ✅ Het is veilig: alleen bedoelde gegevens worden blootgesteld | |
| ✅ Geen onder- of overfetching van gegevens | |
| ✅ Het kan snel zijn, omdat alle gegevens in één verzoek worden opgehaald | POST |
| ✅ Het maakt snelle iteratie van het project mogelijk | |
| ✅ Het kan zichzelf documenteren | |
| ✅ Het biedt een editor voor de query (GraphiQL) die de taak vereenvoudigt |
De Persisted Query uitvoeren
Zodra de persisted query is gepubliceerd, kunnen we deze uitvoeren via de permalink.
De persisted query kan rechtstreeks in de browser worden uitgevoerd, omdat deze toegankelijk is via GET, en we ontvangen de gevraagde gegevens in JSON-formaat:
Een Persisted Query aanmaken
Door op de link Persisted Queries in het menu te klikken, wordt de lijst van alle aangemaakte persisted queries weergegeven:
Een persisted query is een aangepast berichttype (CPT). Om een nieuwe persisted query aan te maken, klik je op de knop "Add New GraphQL persisted query", waarmee de WordPress-editor wordt geopend:
Het belangrijkste invoerelement is de GraphiQL-client, die standaard wordt geleverd met de Explorer. Door op de velden in het linker zijpaneel te klikken, worden ze aan de query toegevoegd, en door op de knop "Run" te klikken, wordt de query uitgevoerd:
Wanneer de query klaar is, publiceer je deze en wordt de permalink het endpoint. De link naar het endpoint (en naar de bron) wordt weergegeven in het zijpaneel "Persisted Query Endpoint Overview":
Door ?view=source aan de permalink toe te voegen, wordt de persisted query en de configuratie ervan weergegeven (zolang de gebruiker is ingelogd en de gebruikersrol er toegang toe heeft):
Standaard heeft het endpoint van de persisted query het pad /graphql-query/, en deze waarde is configureerbaar via de Instellingen:
Schema-configuratie
Het bepalen welke elementen het schema bevat en welke toegang gebruikers ertoe hebben, wordt gedefinieerd in de schema-configuratie.
We moeten dus een schema-configuratie aanmaken en deze vervolgens selecteren uit het vervolgkeuzemenu:
Persisted Queries organiseren per categorie
In het zijpaneel "Endpoint categories" kunnen we categorieën toevoegen om de Persisted Query te beheren:
We kunnen bijvoorbeeld categorieën aanmaken om endpoints te beheren per klant, applicatie of andere benodigde informatie:
In de lijst van Persisted Queries kunnen we hun categorieën bekijken, en door op een categorielink te klikken of het filter bovenaan te gebruiken, worden alleen de vermeldingen voor die categorie weergegeven:
Privé persisted queries
Door de status van de Persisted Query in te stellen op private, is het endpoint alleen toegankelijk voor de beheerder. Dit voorkomt dat onze gegevens onbedoeld worden gedeeld met gebruikers die er geen toegang toe zouden mogen hebben.
We kunnen bijvoorbeeld privé Persisted Queries aanmaken die helpen bij het beheren van de applicatie, zoals het ophalen van gegevens om rapporten met onze statistieken te maken.
Met wachtwoord beveiligde persisted queries
Als we een Persisted Query aanmaken voor een specifieke klant, kunnen we er een wachtwoord aan toewijzen om een extra beveiligingsniveau te bieden, zodat alleen die klant toegang heeft tot het endpoint.
Bij de eerste toegang tot een met wachtwoord beveiligde persisted query verschijnt er een scherm dat om het wachtwoord vraagt:
Pas nadat het wachtwoord is ingevoerd en gevalideerd, krijgt de gebruiker toegang tot het bedoelde endpoint.
De persisted query dynamisch maken via URL-parameters
De waarde van elke variabele kan worden ingesteld via een URL-parameter (met de naam van de variabele) bij het uitvoeren van de persisted query. Als de optie "Overschrijven URL-parameters variabelen?" is ingeschakeld, heeft de URL-parameter prioriteit. Anders heeft de waarde die is gedefinieerd in het variabelenwoordenboek prioriteit (indien aanwezig).
In deze query wordt het aantal resultaten bijvoorbeeld bestuurd via de variabele $limit, met een standaardwaarde van 3:
Bij het uitvoeren van deze persisted query met ?limit=5 wordt de query uitgevoerd en worden er 5 resultaten teruggegeven:
