GraphQL und GraphiQL #

Diese Seite richtet sich an Entwickler, die Inhalte mit GraphQL abfragen. Die DXP liefert ibexa/graphql und den Explorer GraphiQL (overblog/graphiql-bundle) mit. Das Schema ist "auto-generated from the content type model" (Anleitung des Skeletons, Abschnitt 11).

Inhalt #

1. Der Endpunkt
2. Das Schema
3. Der Explorer
4. Authentifizierung
5. Eine erste Abfrage
6. Gute Gewohnheiten

Der Endpunkt #

/graphql, festgelegt in config/routes/graphql.yaml (Route overblog_graphql_endpoint). Clients senden POST-Anfragen mit einem JSON-Körper, der die Abfrage enthält.

Das Schema #

Erzeugen Sie es nach der Installation und nach jeder Änderung an Inhaltstypen oder Feldtypen:

php bin/console ibexa:graphql:generate-schema
php bin/console cache:clear

Der Befehl schreibt YAML-Typdateien in config/graphql/types/ibexa/ Ihres Projekts (das Verzeichnis, das die Erweiterungsklasse des Pakets festlegt). Committen Sie diese Dateien: Sie sind Teil Ihrer API. Ein Inhaltstyp wird zu einem GraphQL-Typ und seine Felder zu typisierten Feldern; die Umbenennung eines Feldbezeichners ändert also Ihre API.

Der Befehl trägt noch seinen Upstream-Namen; es gibt keinen Alias exponential: dafür (Konsolenbefehle).

Der Explorer #

In APP_ENV=dev lädt die Routendatei config/routes/dev/graphiql.yaml die Routen des GraphiQL-Bundles; in einem installierten v5-Projekt antwortet der Explorer unter /graphiql. Die Anleitung des Skeletons nennt /graphql/explorer; prüfen Sie Ihr Projekt mit php bin/console debug:router | grep graphiql. In der Produktion ist der Explorer nicht geroutet.

Authentifizierung #

Ohne Zugangsdaten laufen Abfragen als anonymer Benutzer und sehen, was diese Rolle lesen darf. Apps verwenden JWT: Die security.yaml des Rezepts hat dafür eine auskommentierte Firewall ibexa_jwt_graphql (JWT-Authentifizierung).

Eine erste Abfrage #

Öffnen Sie den Explorer, sehen Sie im Dokumentationsbereich die Typen an, die Ihr Inhaltsmodell erzeugt hat, und beginnen Sie von dort. Die Namen von Typen und Feldern hängen von Ihren Inhaltstypen ab; kopieren Sie sie also aus dem Bereich statt aus einem Beispiel.

Gute Gewohnheiten #

• Fragen Sie nur die Felder ab, die Sie brauchen; GraphQL macht das leicht, und es hält Antworten klein.
• Erzeugen und committen Sie das Schema in derselben Änderung wie eine Änderung eines Inhaltstyps, damit Code und API Schritt halten.
• Testen Sie Abfragen in der CI gegen ein Projekt, das aus Ihren Ausgangsdaten installiert wurde.
• Vergleichen Sie bei Integrationen, die viel schreiben, mit der REST-API (Die REST-API).

Verwandte Seiten #

• Headless mit der DXP
• Inhalte, Inhaltstypen und Platzierungen
• JWT-Authentifizierung
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.