docs/content/graphql/guides/migrating-from-rest-to-graphql.md at main · github/docs · GitHub Skip to content Navigation Menu Sign in Appearance settings * Platform * AI CODE CREATION * GitHub Copilot Write better code with AI * GitHub Copilot app Direct agents from issue to merge * MCP Registry Integrate external tools * DEVELOPER WORKFLOWS * Actions Automate any workflow * Codespaces Instant dev environments * Issues Plan and track work * Code Review Manage code changes * Code Quality Enforce quality at merge * APPLICATION SECURITY * GitHub Advanced Security Find and fix vulnerabilities * Code security Secure your code as you build * Secret protection Stop leaks before they start * EXPLORE * Why GitHub * Documentation * Blog * Changelog * Marketplace View all features * Solutions * BY COMPANY SIZE * Enterprises * Small and medium teams * Startups * Nonprofits * BY USE CASE * App Modernization * DevSecOps * DevOps * CI/CD * View all use cases * BY INDUSTRY * Healthcare * Financial services * Manufacturing * Government * View all industries View all solutions * Resources * EXPLORE BY TOPIC * AI * Software Development * DevOps * Security * View all topics * EXPLORE BY TYPE * Customer stories * Events & webinars * Ebooks & reports * Business insights * GitHub Skills * SUPPORT & SERVICES * Documentation * Customer support * Community forum * Trust center * Partners View all resources * Open Source * COMMUNITY * GitHub Sponsors Fund open source developers * PROGRAMS * Security Lab * Maintainer Community * GitHub Stars * Archive Program * REPOSITORIES * Topics * Trending * Collections * Enterprise * ENTERPRISE SOLUTIONS * Enterprise platform AI-powered developer platform * AVAILABLE ADD-ONS * GitHub Advanced Security Enterprise-grade security features * Copilot for Business Enterprise-grade AI features * Premium Support Enterprise-grade 24/7 support * Pricing Search / Sign in Sign up Appearance settings You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert Uh oh! There was an error while loading. Please reload this page . github / docs Public * Notifications You must be signed in to change notification settings * Fork 68.6k * Star 20.8k * Code * Issues 32 * Pull requests 19 * Actions * Projects * Security and quality 0 * Insights Additional navigation options * Code * Issues * Pull requests * Actions * Projects * Security and quality * Insights Files Expand file tree main Breadcrumbs * docs * / content * / graphql * / guides / migrating-from-rest-to-graphql.md Copy path Blame More file actions Blame More file actions Latest commit   History History History 218 lines (185 loc) · 6.25 KB main Breadcrumbs * docs * / content * / graphql * / guides / migrating-from-rest-to-graphql.md Copy path Top File metadata and controls * Preview * Code * Blame 218 lines (185 loc) · 6.25 KB Raw Copy raw file Download raw file Outline Edit and raw actions title Migrating from REST to GraphQL intro Learn best practices and considerations for migrating from {% data variables.product.prodname_dotcom %}'s REST API to {% data variables.product.prodname_dotcom %}'s GraphQL API. redirect_from /v4/guides/migrating-from-rest /graphql/guides/migrating-from-rest versions fpt ghec ghes * * * shortTitle Migrate from REST to GraphQL category Understand API changes and limits Differences in API logic {% data variables.product.company_short %} provides two APIs: a REST API and a GraphQL API. For more information about {% data variables.product.company_short %}'s APIs, see AUTOTITLE . 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 {% data variables.product.rest_url %}/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 {% data variables.product.rest_url %}/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 {% data variables.product.rest_url %}/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 {% data variables.product.rest_url %}/repos/:owner/:repo/pulls/:number curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/pulls/:number/commits curl -v {% data variables.product.rest_url %}/repos/:owner/:repo/issues/:number/comments curl -v {% data variables.product.rest_url %}/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 } } } } } Footer (c) 2026 GitHub, Inc. Footer navigation * Terms * Privacy * Security * Status * Community * Docs * Contact * Manage cookies * Do not share my personal information You can’t perform that action at this time.