Migrating from REST to GraphQL - GitHub Docs Skip to main content GitHub Docs Version: Free, Pro, & Team Search or ask Copilot Search or ask Copilot Select language: current language is English Search or ask Copilot Search or ask Copilot Open menu Collapse sidebar Expand sidebar Scroll breadcrumbs left * Home * GraphQL API * Guides * Migrate from REST to GraphQL Scroll breadcrumbs right GraphQL API * * * Overview * About the GraphQL API * Public schema * Breaking changes * Changelog * 2026 * 2025 * 2024 * 2023 * 2022 * 2021 * 2020 * 2019 * 2018 * 2017 * Rate and query limits * Reference * Actions * Activity * GitHub Apps * Branches * Checks * Commits * Copilot * Dependabot * Dependency graph * Deploy keys * Deployments * Discussions * Enterprise administration * Gists * Git * Issues * Licenses * Meta * Migrations * Organizations * Packages * Projects * Projects (classic) * Pull requests * Reactions * Releases * Repositories * Search * Security advisories * Sponsors * Teams * Users * Other * Guides * Introduction to GraphQL * Form calls with GraphQL * Using global node IDs * Migrate from REST to GraphQL * Using GraphQL Clients * Pagination * Use GraphQL for Discussions * Migrating global node IDs Migrating from REST to GraphQL Learn best practices and considerations for migrating from GitHub's REST API to GitHub's GraphQL API. Copy as Markdown In this article * Differences in API logic * Example: Getting the data you need and nothing more * Example: Nesting * Example: Strong typing Differences in API logic GitHub 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 . Migrating 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. To migrate your code from the REST API to the GraphQL API: * Review the GraphQL spec * Review GitHub's GraphQL schema * Consider how any existing code you have currently interacts with the GitHub REST API * Use Global Node IDs to reference objects between API versions Significant advantages of GraphQL include: * Getting the data you need and nothing more * Nested fields * Strong typing Here are examples of each. Example: Getting the data you need and nothing more A single REST API call retrieves a list of your organization's members: curl -v https://api.github.com/orgs/:org/members The 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: query { organization ( login : "github" ) { membersWithRole ( first : 100 ) { edges { node { name avatarUrl } } } } } Consider 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 : curl -v https://api.github.com/repos/:owner/:repo/pulls Determining if a pull request is mergeable requires retrieving each pull request individually for its detailed representation (a large payload) and checking whether its mergeable attribute is true or false: curl -v https://api.github.com/repos/:owner/:repo/pulls/:number With GraphQL, you could retrieve only the number and mergeable attributes for each pull request: query { repository ( owner : "octocat" , name : "Hello-World" ) { pullRequests ( last : 10 ) { edges { node { number mergeable } } } } } Example: Nesting Querying 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: 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 Using the GraphQL API , you can retrieve the data with a single query using nested fields: { 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 } } } } } } You can also extend the power of this query by substituting a variable for the pull request number. Example: Strong typing GraphQL schemas are strongly typed, making data handling safer. Consider an example of adding a comment to an issue or pull request using a GraphQL mutation , and mistakenly specifying an integer rather than a string for the value of clientMutationId : mutation { addComment ( input : { clientMutationId : 1234 , subjectId : "MDA6SXNzdWUyMjcyMDA2MTT=" , body : "Looks good to me!" } ) { clientMutationId commentEdge { node { body repository { id name nameWithOwner } issue { number } } } } } Executing this query returns errors specifying the expected types for the operation: { "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 } ] } ] } Wrapping 1234 in quotes transforms the value from an integer into a string, the expected type: mutation { addComment ( input : { clientMutationId : "1234" , subjectId : "MDA6SXNzdWUyMjcyMDA2MTT=" , body : "Looks good to me!" } ) { clientMutationId commentEdge { node { body repository { id name nameWithOwner } issue { number } } } } } Back to top Help and support Was this Doc helpful? Yes No Help us make GitHub Docs great! All Docs are open source. See something that's wrong or unclear? Submit a pull request. Make a contribution Still need help? Ask the GitHub community Contact support Expert services Blog GitHub Inc. © 2026 Terms Privacy Status Pricing