Einführung in GraphQL

GraphQL-Terminologie

Die GitHub GraphQL-API stellt eine architektonische und konzeptionelle Abkehr von der GitHub-REST-API dar. Du wirst wahrscheinlich einige neue Begriffe in den Referenzdokumenten zur GraphQL-API vorfinden.

Schema

Ein Schema definiert das Typsystem einer GraphQL-API. Es beschreibt den vollständigen Satz möglicher Daten (Objekte, Felder, Beziehungen, alles), auf die ein Client zugreifen kann. Aufrufe vom Client werden überprüft und für das Schema ausgeführt. Ein Client kann über eine Introspektion Informationen zum Schema abrufen. Das Schema befindet sich auf dem GraphQL-API-Server. Weitere Informationen findest du unter Ermitteln der GraphQL-API.

Feld

In Feld ist dies eine Dateneinheit, die du über ein Objekt abrufen kannst. Wie in der offiziellen GraphQL-Dokumentation angegeben ist „die GraphQL-Abfragesprache grundsätzlich für das Auswählen von Feldern in Objekten konzipiert“.

Die offizielle Spezifikation enthält Folgendes über Felder:

Alle GraphQL-Vorgänge müssen ihre Auswahl bis hin zu den Feldern angeben, die Skalare zurückgeben, um eine eindeutig gestaltete Antwort sicherzustellen.

Dies bedeutet, wenn du versuchst, ein Feld zurückzugeben, das kein Skalar ist, wird bei der Schemaüberprüfung ein Fehler ausgelöst. Du musst geschachtelte Unterfelder hinzufügen, bis alle Felder Skalare zurückgeben.

Argument

Ein Argument ein Satz von an ein bestimmtes Feld angefügten Schlüssel-Wert-Paaren. Einige Felder erfordern ein Argument. Mutationen erfordern ein Eingabeobjekt als Argument.

Implementierung

Im GraphQL-Schema wird eventuell der Begriff _ implementiert_ verwendet, um zu definieren, wie ein Objekt von einer Schnittstelle erbt.

Nachfolgend findest du ein Beispiel für ein Schema, das die X-Schnittstelle und das Y-Objekt definiert:

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

Das bedeutet, dass das Y-Objekt dieselben Felder/Argumente/Rückgabetypen wie die X-Schnittstelle erfordert und gleichzeitig neue Felder hinzufügt, die spezifisch für das Y-Objekt sind. (Das ! bedeutet, dass das Feld erforderlich ist.)

In den Referenzdokumenten findest du Folgendes:

Für jedes Objekt sind unter Implementiert die Schnittstellen aufgeführt, von denen es erbt.
Für jede Schnittstelle sind unter Implementierungen die Objekte aufgeführt, von denen sie erbt.

Verbindung

Verbindungen stellen eine Möglichkeit dar, zugehörige Objekte als Teil desselben Aufrufs abzufragen. Mit Verbindungen kannst du mit nur einem einzelnen GraphQL-Aufruf dasselbe erreichen, wofür in der REST-API mehrere Aufrufe benötigst. Weitere Informationen findest du unter Migrieren von REST zu GraphQL.

Im einem Diagramm werden Punkte durch Linien miteinander verbunden, um dies zu veranschaulichen. Die Punkte sind Knoten, die Linien sind Kanten. Eine Verbindung definiert eine Beziehung zwischen Knoten.

Edge

Kanten stellen Verbindungen zwischen Knoten dar. Wenn du eine Verbindung abfragst, werden ihre Kanten durchlaufen, um zu den Knoten zu gelangen. Jedes edges-Feld verfügt über ein node-Feld und ein cursor-Feld. Cursor werden für die Pagination verwendet. Weitere Informationen findest du unter Verwenden der Paginierung in der GraphQL-API.

Node

Knoten ist ein allgemeiner Begriff für ein Objekt. Du kannst einen Knoten direkt suchen oder über eine Verbindung auf verwandte Knoten zugreifen. Wenn du einen node angibst, dass keinen Skalar zurückgibt, musst du Unterfelder einschließen, bis alle Felder Skalare zurückgeben. Informationen zum Zugreifen auf Knoten-IDs über die REST-API und ihre Verwendung in GraphQL-Abfragen findest du unter Verwenden globaler Knoten-IDs.

Entdecken der GraphQL-API

GraphQL ist introspektiv. Dies bedeutet, dass du ein GraphQL-Schema für Details zu sich selbst abfragen kannst.

Frage __schema ab, um alle Typen aufzulisten, die im Schema definiert sind, und Details zu jedem zu erhalten:

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

Frage __type ab, um Details zu einem beliebigen Typ abzurufen:

query {
  __type(name: "Repository") {
    name
    kind
    description
    fields {
      name
    }
  }
}

Du kannst auch eine Introspektionsabfrage für das Schema über eine GET-Anforderung ausführen:
```
curl -H "Authorization: bearer TOKEN" http(s)://HOSTNAME/api/graphql
```
Hinweis: Wenn du die Antwort "message": "Bad credentials" oder 401 Unauthorized erhältst, solltest du überprüfen, ob du ein gültiges Token verwendest. Wenn der 403-Fehler mit der Meldung Resource not accessible by personal access token angezeigt, stelle sicher, dass fine-grained personal access token auf den richtigen Ressourcenbesitzer abzielt. Es muss beispielsweise auf die Organisation abzielen, die das Repository besitzt, auf das du zugreifen möchtest.

Die Ergebnisse werden in JSON angegeben. Es wird daher empfohlen, zum einfacheren Lesen und Suchen eine Quelltextformatierung durchzuführen. Du kannst ein Befehlszeilentool wie jq verwenden oder die Ergebnisse zu diesem Zweck per Pipe an python -m json.tool weiterleiten.

Alternativ kannst du den Medientyp idl übergeben, um die Ergebnisse im IDL-Format zurückzugeben, das eine komprimierte Version des Schemas darstellt:
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
http(s)://HOSTNAME/api/graphql
```
Hinweis: Die Introspektionsabfrage ist wahrscheinlich die einzige GET-Anforderung, die du in GraphQL ausführst. Wenn du einen Methodenkörper übergibst, ist die GraphQL-Anforderungsmethode POST, und zwar unabhängig davon, ob es sich um eine Abfrage oder eine Mutation handelt.

Weitere Informationen zum Ausführen von Abfragen findest du unter Erstellen von Aufrufen mit GraphQL.

In diesem Artikel