{"meta":{"title":"Migrating from REST to GraphQL","intro":"Learn best practices and considerations for migrating from GitHub's REST API to GitHub's GraphQL API.","product":"GraphQL API","breadcrumbs":[{"href":"/en/graphql","title":"GraphQL API"},{"href":"/en/graphql/guides","title":"Guides"},{"href":"/en/graphql/guides/migrating-from-rest-to-graphql","title":"Migrate from REST to GraphQL"}],"documentType":"article"},"body":"# Migrating from REST to GraphQL\n\nLearn best practices and considerations for migrating from GitHub's REST API to GitHub's GraphQL API.\n\n## Differences in API logic\n\nGitHub provides two APIs: a REST API and a GraphQL API. For more information about GitHub's APIs, see [Comparing GitHub's REST API and GraphQL API](/en/rest/about-the-rest-api/comparing-githubs-rest-api-and-graphql-api).\n\nMigrating from REST to GraphQL represents a significant shift in API logic. The differences between REST as a style and GraphQL as a specification make it difficult—and often undesirable—to replace REST API calls with GraphQL API queries on a one-to-one basis. We've included specific examples of migration below.\n\nTo migrate your code from the [REST API](/en/rest) to the GraphQL API:\n\n* Review the [GraphQL spec](https://spec.graphql.org/June2018/)\n* Review GitHub's [GraphQL schema](/en/graphql/reference)\n* Consider how any existing code you have currently interacts with the GitHub REST API\n* Use [Global Node IDs](/en/graphql/guides/using-global-node-ids) to reference objects between API versions\n\nSignificant advantages of GraphQL include:\n\n* [Getting the data you need and nothing more](#example-getting-the-data-you-need-and-nothing-more)\n* [Nested fields](#example-nesting)\n* [Strong typing](#example-strong-typing)\n\nHere are examples of each.\n\n## Example: Getting the data you need and nothing more\n\nA single REST API call retrieves a list of your organization's members:\n\n```shell\ncurl -v https://api.github.com/orgs/:org/members\n```\n\nThe REST payload contains excessive data if your goal is to retrieve only member names and links to avatars. However, a GraphQL query returns only what you specify:\n\n```graphql\nquery {\n    organization(login:\"github\") {\n    membersWithRole(first: 100) {\n      edges {\n        node {\n          name\n          avatarUrl\n        }\n      }\n    }\n  }\n}\n```\n\nConsider another example: retrieving a list of pull requests and checking if each one is mergeable. A call to the REST API retrieves a list of pull requests and their [summary representations](/en/rest#summary-representations):\n\n```shell\ncurl -v https://api.github.com/repos/:owner/:repo/pulls\n```\n\nDetermining if a pull request is mergeable requires retrieving each pull request individually for its [detailed representation](/en/rest#detailed-representations) (a large payload) and checking whether its `mergeable` attribute is true or false:\n\n```shell\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number\n```\n\nWith GraphQL, you could retrieve only the `number` and `mergeable` attributes for each pull request:\n\n```graphql\nquery {\n    repository(owner:\"octocat\", name:\"Hello-World\") {\n    pullRequests(last: 10) {\n      edges {\n        node {\n          number\n          mergeable\n        }\n      }\n    }\n  }\n}\n```\n\n## Example: Nesting\n\nQuerying with nested fields lets you replace multiple REST calls with fewer GraphQL queries. For example, retrieving a pull request along with its commits, non-review comments, and reviews using the **REST API** requires four separate calls:\n\n```shell\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number/commits\ncurl -v https://api.github.com/repos/:owner/:repo/issues/:number/comments\ncurl -v https://api.github.com/repos/:owner/:repo/pulls/:number/reviews\n```\n\nUsing the **GraphQL API**, you can retrieve the data with a single query using nested fields:\n\n```graphql\n{\n  repository(owner: \"octocat\", name: \"Hello-World\") {\n    pullRequest(number: 1) {\n      commits(first: 10) {\n        edges {\n          node {\n            commit {\n              oid\n              message\n            }\n          }\n        }\n      }\n      comments(first: 10) {\n        edges {\n          node {\n            body\n            author {\n              login\n            }\n          }\n        }\n      }\n      reviews(first: 10) {\n        edges {\n          node {\n            state\n          }\n        }\n      }\n    }\n  }\n}\n```\n\nYou can also extend the power of this query by [substituting a variable](/en/graphql/guides/forming-calls-with-graphql#working-with-variables) for the pull request number.\n\n## Example: Strong typing\n\nGraphQL schemas are strongly typed, making data handling safer.\n\nConsider an example of adding a comment to an issue or pull request using a GraphQL [mutation](/en/graphql/reference), and mistakenly specifying an integer rather than a string for the value of [`clientMutationId`](/en/graphql/reference/issues#mutation-addcomment):\n\n```graphql\nmutation {\n  addComment(input:{clientMutationId: 1234, subjectId: \"MDA6SXNzdWUyMjcyMDA2MTT=\", body: \"Looks good to me!\"}) {\n    clientMutationId\n    commentEdge {\n      node {\n        body\n        repository {\n          id\n          name\n          nameWithOwner\n        }\n        issue {\n          number\n        }\n      }\n    }\n  }\n}\n```\n\nExecuting this query returns errors specifying the expected types for the operation:\n\n```json\n{\n  \"data\": null,\n  \"errors\": [\n    {\n      \"message\": \"Argument 'input' on Field 'addComment' has an invalid value. Expected type 'AddCommentInput!'.\",\n      \"locations\": [\n        {\n          \"line\": 3,\n          \"column\": 3\n        }\n      ]\n    },\n    {\n      \"message\": \"Argument 'clientMutationId' on InputObject 'AddCommentInput' has an invalid value. Expected type 'String'.\",\n      \"locations\": [\n        {\n          \"line\": 3,\n          \"column\": 20\n        }\n      ]\n    }\n  ]\n}\n```\n\nWrapping `1234` in quotes transforms the value from an integer into a string, the expected type:\n\n```graphql\nmutation {\n  addComment(input:{clientMutationId: \"1234\", subjectId: \"MDA6SXNzdWUyMjcyMDA2MTT=\", body: \"Looks good to me!\"}) {\n    clientMutationId\n    commentEdge {\n      node {\n        body\n        repository {\n          id\n          name\n          nameWithOwner\n        }\n        issue {\n          number\n        }\n      }\n    }\n  }\n}\n```"}