Publieke en private endpoints beschikbaar stellen
GraphQL draait traditioneel om het beschikbaar stellen van één enkel endpoint, meestal onder https://mysite.com/graphql.
Gato GraphQL breidt dit concept uit en stelt je in staat meerdere aangepaste endpoints beschikbaar te stellen, elk afgestemd op een specifieke behoefte. We kunnen bijvoorbeeld de volgende endpoints beschikbaar stellen:
/internalen/public/apps/mobileen/apps/website/clientsen/visitors/development,/stagingen/production/teams/development,/teams/testingen/teams/marketing/clients/A,/clients/Benclients/Z- elke combinatie daarvan
Gato GraphQL ondersteunt ook Persisted Queries: endpoints waarbij de GraphQL-query vooraf is gedefinieerd en op de server is opgeslagen.
Deze gids geeft suggesties over hoe en wanneer je elk endpoint gebruikt.
Naast het beveiligen van je Gato GraphQL API-endpoints raden we aan om de beveiliging van je WordPress-site altijd te versterken met een speciale beveiligingsplugin, zoals WP Security Ninja.
Endpoints worden geconfigureerd via een Schema-configuratie, waarin we het volgende definiëren:
- Het schema instellen als publiek of privaat
- "Gevoelige" data-elementen inschakelen
- Het schema van een naamruimte voorzien
- Geneste mutaties gebruiken
- Antwoordheaders definiëren
- Toegang tot schema-elementen verlenen via Access Control Lists
- HTTP-caching instellen
- En nog veel meer
Als we een configuratie hebben die we op alle of de meeste endpoints willen toepassen, kunnen we een standaard Schema-configuratie definiëren.
Wanneer gebruik je het enkele endpoint
Het enkele endpoint is altijd publiek en wordt standaard beschikbaar gesteld onder /graphql.
Gato GraphQL wordt beheerd via "modules", elk met bepaalde functionaliteit of een uitbreiding van het GraphQL-schema, en die naar behoefte in- en uitgeschakeld kunnen worden.
Om de beveiliging van onze API te versterken, is het een goede gewoonte om modules die het GraphQL-schema uitbreiden (zoals de modules "Posts", "Users", "Comments", "Blocks", enz.) uit te schakelen wanneer ze niet nodig zijn, zodat die gegevens nooit worden blootgesteld.
In het bijzonder, als de API niet bedoeld is voor het muteren van gegevens (d.w.z. het aanmaken of bijwerken van resources), is het een goede gewoonte om de module "Mutations" uit te schakelen. Hierdoor worden alle extensies die een mutatie bieden (zoals de modules "Post Mutations", "Comment Mutations", enz.) ook uitgeschakeld, en worden deze mutaties nooit in het GraphQL-schema blootgesteld.
Het enkele endpoint is aanbevolen wanneer:
- We gegevens moeten ophalen voor één specifieke functie, en
- De WordPress-website niet toegankelijk is voor het open internet (d.w.z. het draait op een ontwikkelaarslaptop of achter een firewall)
Dit is bijvoorbeeld het geval bij het bouwen van een headless site (met Next.js, Gatsby of andere).
Wanneer gebruik je publieke aangepaste endpoints
Aangepaste endpoints lijken op het enkele endpoint, maar je kunt er meerdere hebben, elk beschikbaar gesteld onder een eigen URL graphql/{custom-endpoint-slug}/, elk met een andere configuratie.
Aangepaste endpoints bieden beveiliging door obscuriteit: alleen de beoogde doelgroep zou op de hoogte moeten zijn van het bestaan van het aangepaste endpoint en de bijbehorende URL.
Om de beveiliging van de API te versterken, kunnen we de extensie Access Control gebruiken om toegang tot het endpoint te verlenen alleen wanneer:
- De gebruiker is ingelogd (of niet)
- De gebruiker een bepaalde rol heeft
- De gebruiker een bepaalde capability heeft
- De bezoeker afkomstig is van een toegestaan IP-adres (via de extensie Access Control: Visitor IP)
Elk aangepast endpoint kan zijn eigen Access Control List hebben, waardoor het alleen toegankelijk is voor de specifiek beoogde gebruiker.
Aangepaste endpoints zijn aanbevolen wanneer we toegang tot de API moeten beheren en aanpassen, of dat nu door verschillende applicaties, teams, klanten of anderen is.
Wanneer gebruik je private aangepaste endpoints
Gato GraphQL implementeert aangepaste endpoints via Custom Post Types (CPTs). Hierdoor kunnen we het aangepaste endpoint als privaat publiceren (en ook als met wachtwoord beveiligd), waardoor het aangepaste endpoint alleen toegankelijk is voor ingelogde gebruikers die het recht hebben om die aangepaste post te benaderen, en voor niemand anders.
Deze methode is aanbevolen wanneer het GraphQL-endpoint uitsluitend bedoeld is voor gebruik door de beheerder van de site (bijvoorbeeld wanneer GraphQL wordt gebruikt voor het uitvoeren van beheertaken). Door externe bezoekers volledig te blokkeren van toegang tot het endpoint, versterken we de beveiliging van de site.
Wanneer gebruik je publieke Persisted Queries
Persisted queries zijn endpoints, elk met een eigen URL, maar de GraphQL-query is al gedefinieerd aan de serverzijde, waardoor de respons ook vooraf bepaald is (het kan dynamisch worden gemaakt door variabelen te definiëren, te vervullen via URL-parameters).
Persisted queries lijken op REST-endpoints, maar we gebruiken de GraphQL-taal om de query samen te stellen, en we kunnen deze rechtstreeks vanuit de wp-admin publiceren. Er is geen PHP-code nodig om een persisted query te publiceren.
Omdat persisted queries het niet vereisen dat de GraphQL-query in de body van het verzoek wordt meegegeven, zijn ze van nature geschikt om te worden benaderd via GET in plaats van POST.
(Het enkele endpoint en aangepaste endpoints kunnen ook via GET worden benaderd door de parameter ?query={ GraphQL query } aan het endpoint toe te voegen.)
We kunnen hiervan profiteren en de API sneller maken via standaard HTTP-caching, waarbij de GraphQL-respons aan de clientzijde of op tussenniveaus tussen de client en de server (zoals een CDN) wordt gecached.
Dit wordt bereikt via de extensie Cache Control, die automatisch de max-age-waarde van de respons berekent en uitvoert op basis van de velden en directives in de query.
Het is aanbevolen om persisted queries te gebruiken wanneer dat mogelijk is, omdat ze de beveiliging van onze sites aanzienlijk vergroten.
Dit komt doordat alle gegevens die voor onze applicatie beschikbaar moeten worden gesteld, al via persisted queries kunnen worden blootgesteld. Vervolgens kunnen we het beschikbaar stellen van het enkele GraphQL-endpoint (of een aangepast endpoint) overslaan, waardoor we de kans elimineren dat gebruikers toegang krijgen tot privégegevens die we (per ongeluk of anderszins) blootgesteld hebben gelaten.
Wanneer gebruik je private Persisted Queries
Net als aangepaste endpoints zijn persisted queries CPTs, dus we kunnen ze als private (of met wachtwoord beveiligd) publiceren, waardoor ze alleen toegankelijk zijn voor ingelogde gebruikers die het recht hebben om ze te benaderen, en voor niemand anders.
Het is aanbevolen om deze te gebruiken wanneer de queries uitsluitend voor intern gebruik bedoeld zijn, zoals bij het zoeken in WordPress-gegevens voor eigen gebruik.