Öffentliche und private Endpoints bereitstellen
GraphQL dreht sich traditionell darum, einen einzelnen Endpoint bereitzustellen, meistens unter https://mysite.com/graphql.
Gato GraphQL erweitert dieses Konzept und ermöglicht es uns, mehrere benutzerdefinierte Endpoints bereitzustellen, jeden auf einen bestimmten Bedarf zugeschnitten. Zum Beispiel können wir folgende Endpoints bereitstellen:
/internalund/public/apps/mobileund/apps/website/clientsund/visitors/development,/stagingund/production/teams/development,/teams/testingund/teams/marketing/clients/A,/clients/Bundclients/Z- jede beliebige Kombination davon
Gato GraphQL unterstützt außerdem Persisted Queries, also Endpoints, bei denen die GraphQL-Query serverseitig vordefiniert und gespeichert ist.
Diese Anleitung gibt Empfehlungen, wie und wann man welchen Endpoint verwenden sollte.
Zusätzlich zur Absicherung deiner Gato GraphQL API Endpoints empfehlen wir, die Sicherheit deiner WordPress-Website immer mit einem dedizierten Sicherheits-Plugin zu stärken, zum Beispiel mit WP Security Ninja.
Endpoints werden über eine Schema-Konfiguration konfiguriert, wo wir folgendes festlegen:
- Das Schema als öffentlich oder privat einstellen
- „Sensible" Datenelemente aktivieren
- Das Schema mit Namespacing versehen
- Verschachtelte Mutations verwenden
- Antwort-Header definieren
- Zugriff auf Schema-Elemente über Access Control Lists gewähren
- HTTP-Caching einrichten
- Vieles mehr
Wenn wir eine Konfiguration haben, die wir auf alle oder die meisten Endpoints anwenden möchten, können wir eine Standard-Schema-Konfiguration definieren.
Wann man den einzelnen Endpoint verwenden sollte
Der einzelne Endpoint ist immer öffentlich und wird standardmäßig unter /graphql bereitgestellt.
Gato GraphQL wird über „Module" verwaltet, von denen jedes eine Funktionalität oder Erweiterung des GraphQL-Schemas bietet und die je nach Bedarf aktiviert und deaktiviert werden können.
Um die Sicherheit unserer API zu stärken, ist es eine gute Praxis, Module zu deaktivieren, die das GraphQL-Schema erweitern (wie die Module „Posts", „Users", „Comments", „Blocks" usw.), wenn sie nicht benötigt werden – so stellen wir sicher, dass diese Daten gar nicht erst exponiert werden.
Insbesondere wenn die API nicht zur Datenveränderung vorgesehen ist (also zum Erstellen oder Aktualisieren von Ressourcen), ist es eine gute Praxis, das Modul „Mutations" zu deaktivieren. Dadurch werden wiederum alle Erweiterungen deaktiviert, die eine Mutation bereitstellen (wie die Module „Post Mutations", „Comment Mutations" usw.), und diese Mutations werden nie im GraphQL-Schema exponiert.
Der einzelne Endpoint wird empfohlen, wenn:
- Wir Daten für eine einzelne Funktion abrufen müssen, und
- Die WordPress-Website nicht über das öffentliche Internet erreichbar ist (also auf einem Entwicklungs-Laptop läuft oder hinter einer Firewall)
Das ist zum Beispiel der Fall beim Aufbau einer Headless-Website (mit Next.js, Gatsby oder anderen).
Wann man öffentliche benutzerdefinierte Endpoints verwenden sollte
Benutzerdefinierte Endpoints ähneln dem einzelnen Endpoint, aber wir können viele davon haben, jeden unter seiner eigenen URL graphql/{custom-endpoint-slug}/, jeweils mit einer anderen Konfiguration.
Benutzerdefinierte Endpoints bieten Sicherheit durch Obskurität, da nur die beabsichtigte Zielgruppe von der Existenz des benutzerdefinierten Endpoints und seiner URL wissen sollte.
Um die Sicherheit der API weiter zu stärken, können wir die Erweiterung Access Control nutzen, um Zugriff auf den Endpoint zu gewähren nur wenn:
- Der Benutzer eingeloggt ist (oder nicht)
- Der Benutzer eine bestimmte Rolle hat
- Der Benutzer eine bestimmte Capability hat
- Der Besucher von einer erlaubten IP kommt (über die Erweiterung Access Control: Visitor IP)
Jeder benutzerdefinierte Endpoint kann seine eigene Access Control List haben und ist damit nur für seinen spezifischen vorgesehenen Benutzer zugänglich.
Benutzerdefinierte Endpoints werden empfohlen, wenn wir die Zugriffe auf die API verwalten und anpassen müssen, sei es durch verschiedene Anwendungen, Teams, Kunden oder andere.
Wann man private benutzerdefinierte Endpoints verwenden sollte
Gato GraphQL implementiert benutzerdefinierte Endpoints über Custom Post Types (CPTs). Das ermöglicht es uns, den benutzerdefinierten Endpoint als privat zu veröffentlichen (und auch als passwortgeschützt), sodass der benutzerdefinierte Endpoint nur für eingeloggte Benutzer zugänglich ist, die das Recht haben, auf diesen Custom Post zuzugreifen, und für niemanden sonst.
Diese Methode wird empfohlen, wenn der GraphQL-Endpoint nur für den Administrator der Website vorgesehen ist (z.B. wenn GraphQL für administrative Aufgaben verwendet wird). Indem wir externe Besucher vollständig vom Zugriff auf den Endpoint ausschließen, stärken wir die Sicherheit der Website.
Wann man öffentliche Persisted Queries verwenden sollte
Persisted Queries sind Endpoints, jeder mit seiner eigenen URL, aber die GraphQL-Query ist bereits serverseitig definiert, daher ist auch die Antwort vordefiniert (sie kann durch die Definition von Variablen dynamisch gemacht werden, die über URL-Parameter bereitgestellt werden).
Persisted Queries sind ähnlich wie REST-Endpoints, aber wir verwenden die GraphQL-Sprache, um die Query zu erstellen, und wir können sie direkt aus dem wp-admin veröffentlichen. Es ist kein PHP-Code-Deployment nötig, um eine Persisted Query zu veröffentlichen.
Da Persisted Queries das Übergeben der GraphQL-Query im Request-Body nicht erfordern, eignen sie sich von Natur aus für den Zugriff über GET statt POST.
(Der einzelne Endpoint und benutzerdefinierte Endpoints können ebenfalls über GET aufgerufen werden, indem der Parameter ?query={ GraphQL query } an den Endpoint angehängt wird.)
Wir können davon profitieren und die API durch Standard-HTTP-Caching beschleunigen, indem wir die GraphQL-Antwort clientseitig oder in Zwischenstufen zwischen Client und Server (wie einem CDN) cachen.
Dies wird durch die Erweiterung Cache Control erreicht, die den max-age-Wert der Antwort automatisch berechnet und ausgibt, basierend auf den Feldern und Direktiven in der Query.
Es wird empfohlen, Persisted Queries wann immer möglich zu verwenden, da sie die Sicherheit unserer Websites erheblich erhöhen.
Das liegt daran, dass alle Daten, die für unsere Anwendung verfügbar gemacht werden müssen, bereits über Persisted Queries exponiert werden können. Dann können wir darauf verzichten, den einzelnen GraphQL-Endpoint (oder einen benutzerdefinierten Endpoint) zu exponieren, und so die Möglichkeit ausschließen, dass Benutzer auf private Daten zugreifen könnten, die wir (versehentlich oder anderweitig) exponiert gelassen haben.
Wann man private Persisted Queries verwenden sollte
Ähnlich wie benutzerdefinierte Endpoints sind Persisted Queries CPTs, daher können wir sie als private (oder passwortgeschützt) veröffentlichen, sodass sie nur für eingeloggte Benutzer zugänglich sind, die das Recht haben, darauf zuzugreifen, und für niemanden sonst.
Es wird empfohlen, diese immer dann zu verwenden, wenn die Query nur für den internen Gebrauch bestimmt ist, z.B. wenn WordPress-Daten für den eigenen Bedarf durchsucht werden.