Migrieren von REST zu GraphQL

Unterschiede in der API-Logik

GitHub stellt zwei APIs bereit: eine REST-API und eine GraphQL-API. Weitere Informationen zu den GitHub-APIs findest du unter Vergleich der REST-API und der GraphQL-API von GitHub.

Beim Migrieren von REST zu GraphQL ändert sich die API-Logik drastisch. Die Unterschiede zwischen REST als Stil und GraphQL als Spezifikation gestalten es oft schwierig (und lästig), REST-API-Aufrufe eins zu eins durch GraphQL-API-Abfragen zu ersetzen. Unten findest du spezifische Beispiele für die Migration.

So migrierst du deinen Code aus der REST-API zur GraphQL-API:

• Überprüfe die GraphQL-Spezifikation.
• Überprüfen Sie das GraphQL-Schema GitHub
• Überlegen Sie, wie vorhandener Code derzeit mit der REST-API GitHub interagiert.
• Verwenden Sie Global Node IDs, um zwischen API-Versionen auf Objekte zu verweisen.

Folgendes gehört zu den wichtigsten Vorteilen von GraphQL:

•         [Genau die benötigten Daten und nichts darüber hinaus abrufen.](#example-getting-the-data-you-need-and-nothing-more)
  

•         [Geschachtelte Felder](#example-nesting)
  

•         [Starke Typisierung](#example-strong-typing)
  

Im Folgenden findest du Beispiele zu jedem Vorteil.

Beispiel: Nur die benötigten Daten werden erhalten, und nichts mehr

Ein einzelner REST-API-Aufruf ruft eine Liste der Mitglieder deiner Organisation ab:

curl -v https://api.github.com/orgs/:org/members

Wenn du nur Namen von Mitgliedern und Links zu Avataren abrufen möchtest, enthalten die REST-Nutzdaten eine zu große Datenmenge. Eine GraphQL-Abfrage gibt jedoch nur das zurück, was du angibst:

query {
    organization(login:"github") {
    membersWithRole(first: 100) {
      edges {
        node {
          name
          avatarUrl
        }
      }
    }
  }
}

Weiteres Beispiel: Du rufst eine Liste von Pull Requests ab und überprüfst, ob alle gemergt werden können. Ein Aufruf der REST-API ruft eine Liste der Pull Requests und deren Zusammenfassungsdarstellungen ab:

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

Um festzustellen, ob ein Pull Request zusammengeführt werden kann, muss jeder Pull Request aufgrund der detaillierten Darstellung (einer großen Datenmenge) einzeln abgerufen werden, und du musst überprüfen, ob das mergeable-Attribut true oder false ist.

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

Mit GraphQL kannst du nur die number- und mergeable-Attribute jedes Pull Requests abrufen:

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

Beispiel: Schachtelung

Bei Abfragen mit geschachtelten Felder kannst du anstelle von mehreren REST-Aufrufen weniger GraphQL-Abfragen verwenden. Beispielsweise erfordert das Abrufen eines Pull Requests mit den Commits, nicht überprüften Kommentaren und Reviews mithilfe der REST-API vier separate Aufrufe:

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

Mit der GraphQL-API kannst du die Daten mit einer einzelnen Abfrage und verschachtelten Feldern abrufen.

{
  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
          }
        }
      }
    }
  }
}

Sie können die Leistungsfähigkeit dieser Abfrage auch durch substituieren einer Variablen für die Pullanforderungsnummer erweitern.

Beispiel: Starke Typisierung

GraphQL-Schemas sind stark typisiert, wodurch der Umgang mit Daten sicherer wird.

Stelle dir vor, dass du mithilfe einer GraphQL-Mutation einen Kommentar zu einem Issue oder Pull Request hinzufügst und versehentlich eine ganze Zahl anstelle einer Zeichenfolge für den Wert von clientMutationId angibst:

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

Die Ausführung dieser Abfrage gibt Fehler zurück, die angeben, welche Typen bei dem Vorgang erwartet werden:

{
  "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
        }
      ]
    }
  ]
}

Wenn du 1234 mit Anführungszeichen umschließt, wird der Wert von einer ganzen Zahl in eine Zeichenfolge (den erwarteten Typ) umgewandelt:

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