Différences dans la logique d’API
GitHub fournit deux API : une API REST et une API GraphQL. Pour plus d’informations sur GitHubles API, consultez Comparaison de l'API REST de GitHub et de l'API GraphQL.
La migration de REST vers GraphQL représente un changement important dans la logique d’API. Les différences entre REST en tant que style et GraphQL en tant que spécification rendent difficile, et souvent non souhaitable, le remplacement individuel des appels d’API REST par des requêtes d’API GraphQL. Nous avons inclus des exemples spécifiques de migration ci-dessous.
Pour migrer votre code de l’API REST vers l’API GraphQL :
- Examinez la spécification GraphQL
- Passez en revue le schéma GraphQL de GitHub
- Réfléchissez à la façon dont le code existant que vous avez actuellement interagit avec l’API REST GitHub
- Utilisez les ID de nœud Global Node pour référencer des objets entre les versions de l’API
GraphQL présente les avantages significatifs suivants :
Voici quelques exemples de chacun d’entre eux.
Exemple : Obtention des données dont vous avez besoin, et rien de plus
Un seul appel d’API REST récupère une liste des membres de votre organisation :
curl -v http(s)://HOSTNAME/api/v3/orgs/:org/members
La charge utile REST contient des données excessives si votre objectif est de récupérer uniquement des noms de membres et des liens vers des avatars. En revanche, une requête GraphQL retourne uniquement ce que vous spécifiez :
query {
organization(login:"github") {
membersWithRole(first: 100) {
edges {
node {
name
avatarUrl
}
}
}
}
}
Prenons un autre exemple : récupération d’une liste de demandes de tirage (pull request) et vérification de la possibilité, pour chacune d’elles, d’être fusionnée. Un appel à l’API REST récupère une liste de demandes de tirage et leurs représentations récapitulatives :
curl -v http(s)://HOSTNAME/api/v3/repos/:owner/:repo/pulls
Déterminer si une demande de tirage peut être fusionnée nécessite de récupérer chaque demande de tirage individuellement pour obtenir sa représentation détaillée (une charge utile volumineuse) et de vérifier si son attribut mergeable a la valeur true ou false :