À propos des API de GitHub
GitHub fournit deux API : une API REST et une API GraphQL. Vous pouvez interagir avec les deux API en utilisant GitHub CLI, curl, les bibliothèques Octokit officielles et les bibliothèques tierces. Parfois, une fonctionnalité peut être prise en charge par une API mais pas par l’autre.
Vous devez utiliser l’API qui répond le mieux à vos besoins et qui vous convient le mieux. Vous n’avez pas besoin d’utiliser exclusivement une API plutôt que l’autre. Les ID de nœud vous permettent de passer de l’API REST à l’API GraphQL, et inversement. Pour plus d’informations, consultez « Utilisation d’ID de nœud globaux ».
Cet article décrit les avantages de chaque API. Pour plus d’informations sur l’API GraphQL, consultez « À propos de l’API GraphQL ». Pour plus d’informations sur l’API REST, consultez « Informations sur l’API REST ».
Choix de l’API GraphQL
L’API GraphQL retourne exactement les données que vous demandez. GraphQL retourne également les données dans une structure connue au préalable en fonction de votre demande. En revanche, l’API REST retourne plus de données que vous n’en avez demandé, et les retourne selon une structure prédéfinie. Vous pouvez également effectuer l’équivalent de plusieurs requêtes d’API REST dans une seule requête GraphQL. L’exécution de moins de requêtes et l’extraction de moins de données rend GraphQL attrayant pour les développeurs d’applications mobiles.
Par exemple, pour obtenir les connexions GitHub Enterprise Server de dix de vos abonnés, et les connexions de dix abonnés de chacun de vos abonnés, vous pouvez envoyer une seule requête semblable à ce qui suit :
{
viewer {
followers(first: 10) {
nodes {
login
followers(first: 10) {
nodes {
login
}
}
}
}
}
}
La réponse est un objet JSON qui suit la structure de votre requête.
En revanche, pour obtenir ces mêmes informations de la part de l’API REST, vous devez d’abord envoyer une requête à GET /user/followers. L’API retourne la connexion de chaque abonné ainsi que d’autres données sur les abonnés dont vous n’avez pas besoin. Vous devez ensuite envoyer une requête à GET /users/{username}/followers pour chaque abonné. Au total, vous devez effectuer 11 requêtes pour obtenir les mêmes informations qu’à partir d’une seule requête GraphQL, et vous recevez des données en trop.
Choix de l’API REST
Dans la mesure où les API REST existent depuis plus longtemps que les API GraphQL, certains développeurs sont plus à l’aise avec l’API REST. Dans la mesure où les API REST utilisent des verbes et des concepts HTTP standard, de nombreux développeurs connaissent déjà les concepts de base pour utiliser l’API REST.
Par exemple, pour créer un problème dans le dépôt octocat/Spoon-Knife, vous devez envoyer une requête à POST /repos/octocat/Spoon-Knife/issues avec un corps de requête JSON :
{
"title": "Bug with feature X",
"body": "If you do A, then B happens"
}
En revanche, pour signaler un problème à l’aide de l’API GraphQL, vous devez obtenir l’ID de nœud du dépôt octocat/Spoon-Knife, puis envoyer une requête semblable à ce qui suit :
mutation {
createIssue(
input: {
repositoryId: "MDEwOlJlcG9zaXRvcnkxMzAwMTky"
title: "Bug with feature X"
body: "If you do A, then B happens"}
) {
issue {
number
url
}
}
}