Persisted Queries
Verwende GraphQL-queries, um vordefinierte Endpoints wie in REST zu erstellen und dabei die Vorteile beider APIs zu nutzen.
Beschreibung
Mit REST erstellst du mehrere Endpoints, von denen jeder einen vordefinierten Datensatz zurĂŒckgibt.
| Vorteile | Nachteile |
|---|---|
| â Es ist einfach | â Es ist mĂŒhsam, alle Endpoints zu erstellen |
â
Zugriff ĂŒber GET oder POST | â Ein Projekt kann auf EngpĂ€sse stoĂen, wĂ€hrend auf die Fertigstellung der Endpoints gewartet wird |
| â Kann auf dem Server oder CDN gecacht werden | â Die Erstellung von Dokumentation ist obligatorisch |
| â Es ist sicher: Nur vorgesehene Daten werden bereitgestellt | â Es kann langsam sein (vor allem bei mobilen Apps), da die Anwendung möglicherweise mehrere Anfragen benötigt, um alle Daten abzurufen |
Mit GraphQL stellst du eine beliebige query an einen einzigen Endpoint, der genau die angeforderten Daten zurĂŒckgibt.
| Vorteile | Nachteile |
|---|---|
| â Kein Under- oder Over-Fetching von Daten | â Zugriff nur ĂŒber POST |
| â Es kann schnell sein, da alle Daten in einer einzigen Anfrage abgerufen werden | â Es kann nicht auf dem Server oder CDN gecacht werden, was es langsamer und teurer macht als nötig |
| â Es ermöglicht schnelle Iteration des Projekts | â Kann erfordern, das Rad neu zu erfinden, z. B. beim Hochladen von Dateien oder beim Caching |
| â Es kann selbst-dokumentierend sein | â Muss mit zusĂ€tzlichen KomplexitĂ€ten umgehen, wie dem N+1-Problem |
| â Es stellt einen Editor fĂŒr die query (GraphiQL) bereit, der die Aufgabe vereinfacht | Â |
Persisted queries kombinieren diese 2 AnsÀtze:
- Sie verwenden GraphQL, um queries zu erstellen und aufzulösen
- Aber anstatt einen einzigen Endpoint bereitzustellen, stellen sie jede vordefinierte query unter ihrem eigenen Endpoint bereit
So erhalten wir mehrere Endpoints mit vordefinierten Daten wie in REST, die aber mit GraphQL erstellt wurden â und so die Vorteile beider AnsĂ€tze nutzen und deren Nachteile vermeiden:
| Vorteile | Nachteile |
|---|---|
â
Zugriff ĂŒber GET oder POST | |
| â Kann auf dem Server oder CDN gecacht werden | |
| â Es ist sicher: Nur vorgesehene Daten werden bereitgestellt | |
| â Kein Under- oder Over-Fetching von Daten | |
| â Es kann schnell sein, da alle Daten in einer einzigen Anfrage abgerufen werden | POST |
| â Es ermöglicht schnelle Iteration des Projekts | |
| â Es kann selbst-dokumentierend sein | |
| â Es stellt einen Editor fĂŒr die query (GraphiQL) bereit, der die Aufgabe vereinfacht |
AusfĂŒhren der Persisted Query
Sobald die persisted query veröffentlicht ist, können wir sie ĂŒber ihren Permalink ausfĂŒhren.
Die persisted query kann direkt im Browser ausgefĂŒhrt werden, da sie ĂŒber GET aufgerufen wird, und wir erhalten die angeforderten Daten im JSON-Format:
Erstellen einer Persisted Query
Wenn du auf den Link Persisted Queries im MenĂŒ klickst, wird die Liste aller erstellten persisted queries angezeigt:
Eine persisted query ist ein Custom Post Type (CPT). Um eine neue persisted query zu erstellen, klicke auf die SchaltflÀche "Add New GraphQL persisted query", die den WordPress-Editor öffnet:
Die Haupteingabe ist der GraphiQL-Client, der standardmĂ€Ăig mit dem Explorer geliefert wird. Durch Klicken auf die Felder im linken Seitenbereich werden sie zur query hinzugefĂŒgt, und durch Klicken auf die SchaltflĂ€che "Run" wird die query ausgefĂŒhrt:
Wenn die query fertig ist, veröffentliche sie â ihr Permalink wird dann zu ihrem Endpoint. Der Link zum Endpoint (und zur Quelle) wird im Seitenbereich "Persisted Query Endpoint Overview" angezeigt:
Durch AnhÀngen von ?view=source an den Permalink werden die persisted query und ihre Konfiguration angezeigt (sofern der Nutzer eingeloggt ist und die Nutzerrolle Zugriff darauf hat):
StandardmĂ€Ăig hat der Endpoint der persisted query den Pfad /graphql-query/, und dieser Wert ist ĂŒber die Einstellungen konfigurierbar:
Schema-Konfiguration
Was das Schema enthÀlt und welchen Zugriff Nutzer darauf haben, wird in der Schema-Konfiguration festgelegt.
Daher mĂŒssen wir eine Schema-Konfiguration erstellen und sie dann aus dem Dropdown auswĂ€hlen:
Persisted Queries nach Kategorie organisieren
Im Seitenbereich "Endpoint categories" können wir Kategorien hinzufĂŒgen, um die Verwaltung der Persisted Query zu erleichtern:
Zum Beispiel können wir Kategorien erstellen, um Endpoints nach Kunde, Anwendung oder anderen erforderlichen Informationen zu verwalten:
In der Liste der Persisted Queries können wir ihre Kategorien einsehen, und durch Klicken auf einen Kategorie-Link oder Verwendung des Filters oben werden nur die EintrÀge dieser Kategorie angezeigt:
Private persisted queries
Durch Setzen des Status der Persisted Query auf private kann der Endpoint nur vom Admin-Nutzer aufgerufen werden. Dies verhindert, dass unsere Daten unbeabsichtigt mit Nutzern geteilt werden, die keinen Zugriff darauf haben sollten.
Zum Beispiel können wir private Persisted Queries erstellen, die bei der Verwaltung der Anwendung helfen, wie etwa das Abrufen von Daten zur Erstellung von Berichten mit unseren Metriken.
PasswortgeschĂŒtzte persisted queries
Wenn wir eine Persisted Query fĂŒr einen bestimmten Kunden erstellen, können wir ihr ein Passwort zuweisen, um eine zusĂ€tzliche Sicherheitsstufe zu bieten und sicherzustellen, dass nur dieser Kunde auf den Endpoint zugreifen kann.
Beim ersten Zugriff auf eine passwortgeschĂŒtzte persisted query erscheint ein Bildschirm, der nach dem Passwort fragt:
Erst nachdem das Passwort eingegeben und validiert wurde, erhÀlt der Nutzer Zugriff auf den vorgesehenen Endpoint.
Die persisted query ĂŒber URL-Parameter dynamisch machen
Der Wert jeder Variable kann beim AusfĂŒhren der persisted query ĂŒber einen URL-Parameter (mit dem Variablennamen) festgelegt werden. Wenn die Option "Ăberschreiben URL-Parameter die Variablen?" aktiviert ist, hat der URL-Parameter Vorrang. Andernfalls hat der im Variablen-Dictionary definierte Wert Vorrang (falls vorhanden).
In dieser query wird beispielsweise die Anzahl der Ergebnisse ĂŒber die Variable $limit gesteuert, mit einem Standardwert von 3:
Beim AusfĂŒhren dieser persisted query mit dem Parameter ?limit=5 wird die query mit 5 Ergebnissen ausgefĂŒhrt:
