Informationen zu den APIs von GitHub
GitHub stellt zwei APIs bereit: eine REST-API und eine GraphQL-API. Du kannst mit beiden APIs interagieren, indem du GitHub CLI, curl, die offiziellen Octokit-Bibliotheken und Bibliotheken von Drittanbietern verwendest. Gelegentlich kann ein Feature in einer API unterstützt werden, aber nicht für die andere.
Du solltest die API verwenden, die deinen Anforderungen am besten entspricht und mit der du am besten vertraut bist. Du musst nicht einer API gegenüber der anderen den Vorzug geben. Mit Knoten-IDs kannst du zwischen der REST-API und der GraphQL-API wechseln. Weitere Informationen findest du unter Verwenden globaler Knoten-IDs.
In diesem Artikel werden die jeweiligen Vorteile der beiden APIs erläutert. Weitere Informationen zur GraphQL-API findest du unter Informationen zur GraphQL-API. Weitere Informationen zur REST-API findest du unter Informationen zur REST-API.
Verwenden der GraphQL-API
Von der GraphQL-API werden genau die Daten zurückgegeben, die du anforderst. Außerdem werden die Daten von GraphQL auch in einer vordefinierten Struktur basierend auf deiner Anforderung zurückgegeben. Im Gegensatz dazu werden von der REST-API mehr Daten zurückgegeben, als du angefordert hast; außerdem werden die Daten in einer vordefinierten Struktur zurückgegeben. Du kannst auch die Entsprechung mehrerer REST-API-Anforderungen in einer einzelnen GraphQL-Anforderung ausführen. Die Möglichkeit, weniger Anforderungen auszuführen und weniger Daten abzurufen, macht GraphQL für Entwickler mobiler Anwendungen attraktiv.
Wenn du beispielsweise die GitHub Enterprise Server-Anmeldung von zehn deiner Follower und die Anmeldung von zehn Followern von jedem deiner Follower erhalten möchtest, kannst du eine einzelne Anforderung wie die folgende senden:
{
viewer {
followers(first: 10) {
nodes {
login
followers(first: 10) {
nodes {
login
}
}
}
}
}
}
Die Antwort ist ein JSON-Objekt, das der Struktur der Anforderung folgt.
Im Gegensatz dazu musst du zunächst eine Anforderung an GET /user/followers senden, um dieselben Informationen von der REST-API zu erhalten. Die API gibt die Anmeldung jedes Followers zusammen mit anderen Daten über die Follower zurück, die du nicht benötigst. Dann müsstest du für jeden Follower eine Anforderung an GET /users/{username}/followers ausführen. Insgesamt müsstest du 11 Anforderungen ausführen, um dieselben Informationen zu erhalten, die du aus einer einzelnen GraphQL-Anforderung erhalten könntest, und du würdest überschüssige Daten erhalten.
Auswählen der REST-API
Da es REST-APIs schon länger gibt als GraphQL-APIs, sind einige Entwickler mit der REST-API vertrauter. Da von REST-APIs HTTP-Standardverben und -konzepte verwendet werden, sind viele Entwickler bereits mit den grundlegenden Konzepten für die Verwendung der REST-API vertraut.
Beispiel: Zum Erstellen eines Issue im octocat/Spoon-Knife-Repository müsstest du eine Anforderung mit einem JSON-Anforderungstext an POST /repos/octocat/Spoon-Knife/issues senden:
{
"title": "Bug with feature X",
"body": "If you do A, then B happens"
}
Wenn du dagegen ein Issue mit der GraphQL-API erstellen würdest, müsstest du die Knoten-ID des octocat/Spoon-Knife-Repositorys abrufen und dann eine Anforderung wie die folgende senden:
mutation {
createIssue(
input: {
repositoryId: "MDEwOlJlcG9zaXRvcnkxMzAwMTky"
title: "Bug with feature X"
body: "If you do A, then B happens"}
) {
issue {
number
url
}
}
}