Migration de REST vers GraphQL

Différences dans la logique d’API

GitHub fournit deux API : une API REST et une API GraphQL. Pour plus d’informations sur les API de GitHub, 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 :

•         [Obtention des données dont vous avez besoin, et rien de plus](#example-getting-the-data-you-need-and-nothing-more)
  

•         [Champs imbriqués](#example-nesting)
  

•         [Typage fort](#example-strong-typing)
  

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 https://api.github.com/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 https://api.github.com/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 :

curl -v https://api.github.com/repos/:owner/:repo/pulls/:number

Avec GraphQL, vous pouvez récupérer uniquement les attributs number et mergeable de chaque demande de tirage :

query {
    repository(owner:"octocat", name:"Hello-World") {
    pullRequests(last: 10) {
      edges {
        node {
          number
          mergeable
        }
      }
    }
  }
}

Exemple : Imbrication

L’interrogation avec des champs imbriqués vous permet de remplacer plusieurs appels REST par moins de requêtes GraphQL. Par exemple, récupérer une pull request avec ses commits, ses commentaires non liés à une révision et ses critiques à l’aide de l’API REST nécessite quatre appels distincts :

curl -v https://api.github.com/repos/:owner/:repo/pulls/:number
curl -v https://api.github.com/repos/:owner/:repo/pulls/:number/commits
curl -v https://api.github.com/repos/:owner/:repo/issues/:number/comments
curl -v https://api.github.com/repos/:owner/:repo/pulls/:number/reviews

À l’aide de l’API GraphQL, vous pouvez récupérer les données avec une seule requête à l’aide de champs imbriqués :

{
  repository(owner: "octocat", name: "Hello-World") {
    pullRequest(number: 1) {
      commits(first: 10) {
        edges {
          node {
            commit {
              oid
              message
            }
          }
        }
      }
      comments(first: 10) {
        edges {
          node {
            body
            author {
              login
            }
          }
        }
      }
      reviews(first: 10) {
        edges {
          node {
            state
          }
        }
      }
    }
  }
}

Vous pouvez également étendre la puissance de cette requête en substituant une variable pour le numéro de demande de tirage.

Exemple : Typage fort

Les schémas GraphQL sont fortement typés, ce qui rend la gestion des données plus sûre.

Prenons un exemple d’ajout d’un commentaire à un ticket ou à une pull request à l’aide d’une mutation GraphQL, en spécifiant par erreur un entier plutôt qu’une chaîne de caractères pour la valeur de clientMutationId :

mutation {
  addComment(input:{clientMutationId: 1234, subjectId: "MDA6SXNzdWUyMjcyMDA2MTT=", body: "Looks good to me!"}) {
    clientMutationId
    commentEdge {
      node {
        body
        repository {
          id
          name
          nameWithOwner
        }
        issue {
          number
        }
      }
    }
  }
}

L’exécution de cette requête retourne des erreurs spécifiant les types attendus pour l’opération :

{
  "data": null,
  "errors": [
    {
      "message": "Argument 'input' on Field 'addComment' has an invalid value. Expected type 'AddCommentInput!'.",
      "locations": [
        {
          "line": 3,
          "column": 3
        }
      ]
    },
    {
      "message": "Argument 'clientMutationId' on InputObject 'AddCommentInput' has an invalid value. Expected type 'String'.",
      "locations": [
        {
          "line": 3,
          "column": 20
        }
      ]
    }
  ]
}

Placer 1234 entre guillemets transforme la valeur entière en chaîne de caractères, le type attendu :

mutation {
  addComment(input:{clientMutationId: "1234", subjectId: "MDA6SXNzdWUyMjcyMDA2MTT=", body: "Looks good to me!"}) {
    clientMutationId
    commentEdge {
      node {
        body
        repository {
          id
          name
          nameWithOwner
        }
        issue {
          number
        }
      }
    }
  }
}