GraphQL is a data query language. It is:

A specification

• The spec determines the validity of the schema on the API server
• The schema determines the validity of client calls

Strongly typed

• The schema defines an API's type system and all object relationships

Introspective

• A client can query the schema for details about the schema

Hierarchical

• The shape of a GraphQL call mirrors the shape of the JSON data it returns.
• Nested fields let you query for and receive only the data you specify in a single round trip.

An application layer

• GraphQL is not a storage model or a database query language
• The graph refers to graph structures defined in the schema, where nodes define objects and edges define relationships between objects
• The API traverses and returns application data based on the schema definitions, independent of how the data is stored

Why GitHub is using GraphQL

GraphQL offers significantly more flexibility for their integrators. Unlike the REST API v3 endpoints, you can define precisely the data you want and only the data you want. GraphQL lets you replace multiple REST requests with a single call to fetch the data you specify.

About the GraphQL schema reference

The docs in the sidebar are generated from the GraphQL schema. All calls are validated and executed against the schema.

You can access this same content via the Explorer Docs sidebar. You may need to rely on the docs and the schema validation to call the API.

Check out the guides for more information such as authentication and rate limit details.

Public Schema

The GH-GraphQL API is a public schema. This means you can perform introspection against the GraphQL API directly. You can also download the latest version of the public schema here. Here is a brief screenshot of about 30 lines of GraphQL code in the public schema.

The entire schema is about 40,000 lines.

Schema Previews

You can preview upcoming features and changes to the GitHub GraphQL schema before they are added to the GitHub GraphQL API. During the preview period, GitHub may change some features based on developer feedback. Changes are announced on the developer blog without advance notice.

To access a schema preview, you'll need to provide a custom media type in the Accept header for your requests.

Breaking Changes

Breaking changes are any changes that might require action from our integrators. We divide these changes into two categories:

Breaking

• Changes that will break existing queries to the GraphQL API
• For example, removing a field would be a breaking change

Dangerous

• Changes that won't break existing queries but could affect the runtime behavior of clients
• Adding an enum value is an example of a dangerous change

When a new feature is still evolving it is released behind a schema preview. Breaking changes are announced at least three months before making changes to the GraphQL schema, to give integrators time to make the necessary adjustments.

Changelog

The GraphQL schema changelog is a list of recent and upcoming changes to our GraphQL API schema. It includes backwards-compatible changes, schema previews, and upcoming breaking changes.

Breaking changes include changes that will break existing queries or could affect the runtime behavior of clients. For a list of breaking changes and when they will occur see breaking changes log.

Resource Limitations

The GitHub GraphQL API has limitations in place to protect against excessive or abusive calls to GitHub's servers.

Node limit

To pass schema validation, all GraphQL API v4 calls must meet these standards:

• Clients must supply a first or last argument on any connection
• Values of first and last must be within 1-100
• Individual calls cannot request more than 500,000 total nodes

Calculating nodes in a call

These two examples show how to calculate the total nodes in a call.

Simple query

Calculation

Complex query

Calculation

Rate limit

The GraphQL API v4 limit is different from the REST API v3's rate limits because one GraphQL call can replace multiple REST calls. A single complex GraphQL call could be the equivalent of thousands of REST requests. While a single GraphQL call would fall well below the REST API rate limit, the query might be just as expensive for GitHub's servers to compute.

To accurately represent the server cost of a query, the GraphQL API v4 calculates a call's rate limit score based on a normalized scale of points.

• The formula uses first and last arguments on a parent connection and its children to pre-calculate the potential load
• Each new connection has its own point value
• Points are combined with other points from the call into an overall rate limit score

The GraphQL API v4 rate limit is 5,000 points per hour. Note that 5,000 points per hour is not the same as 5,000 calls per hour: the GraphQL API v4 and REST API v3 use different rate limits.

Returning a call's rate limit status

With the REST API v3, you can check the rate limit status by inspecting the returned HTTP headers.

With the GraphQL API v4, you can check the rate limit status by querying fields on the rateLimit object:

query {
  viewer {
    login
  }
  rateLimit {
    limit
    cost
    remaining
    resetAt
  }
}

limit

• Returns the maximum number of points the client is permitted to consume in a 60-minute window.

cost

• Returns the point cost for the current call that counts against the rate limit.

remaining

• Returns the number of points remaining in the current rate limit window.)

resetAt

• Returns the time at which the current rate limit window resets in UTC epoch seconds.

Calculating a rate limit score before running the call

Querying the rateLimit object returns a call's score, but running the call counts against the limit. To avoid this dilemma, you can calculate the score of a call before you run it. The following calculation works out to roughly the same cost that rateLimit { cost } returns.

1. Add up the number of requests needed to fulfill each unique connection in the call. Assume every request will reach the first or last argument limits.
2. Divide the number by 100 and round the result to get the final aggregate cost. This step normalizes large numbers.

Here's an example query and score calculation:

query {
  viewer {
    login
    repositories(first: 100) {
      edges {
        node {
          id

          issues(first: 50) {
            edges {
              node {
                id

                labels(first: 60) {
                  edges {
                    node {
                      id
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This query requires 5,101 requests to fulfill:

• Although we're returning 100 repositories, the API has to connect to the viewer's account once to get the list of repositories. So, requests for repositories = 1
• Although we're returning 50 issues, the API has to connect to each of the 100 repositories to get the list of issues. So, requests for issues = 100
• Although we're returning 60 labels, the API has to connect to each of the 5,000 potential total issues to get the list of labels. So, requests for labels = 5,000
• Total = 5,101

Dividing by 100 and rounding gives us the final score of the query: 51