Versions Compared

Version Old Version 9 New Version 10
Changes made by

Jay Crouch (Unlicensed)

Jay Crouch (Unlicensed)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

About GraphQL

The GraphQL data query language is:

...

  • Query __schema to list all types defined in the schema and get details about each:

    Code Block
    query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

  • Query __type to get details about any type:

    Code Block
    query {
  __type(name: "User") {
    name
    kind
    description
    fields {
      name
    }
  }
}

  • You can also run an introspection query of the schema via a GET request:

    Code Block
    $ curl -H "Authorization: Token token" https://cms.scopear.com/api/v3/graphql

    The results are in JSON, so we recommend pretty-printing them for easier reading and searching. You can use a command-line tool like jq or pipe the results into python -m json.tool for this purpose.

    Note: The introspection query is probably the only GET request you'll run in GraphQL. If you're passing a body, the GraphQL request method is POST, whether it's a query or a mutation.

Resource limitations

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

Node limit

To pass schema validation, all GraphQL API v3 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.

  1. Simple query:

    Code Block
    query {
  organization {
    members(first: 50) {
      edges {
        user:node {
          name

          licences(first: 10) {
            totalCount
            edges {
              license:node {
                product
                state
              }
            }
          }
        }
      }
    }
  }
}

    Calculation:

    Code Block
    50         = 50 users
 +
50 x 10    = 500 user licences

           = 550 total nodes

  2. Complex query:

    Code Block
    query {
  organization {
    members(first: 50) {
      edges {
        user:node {
          name

          groups(first: 20) {
            edges {
              group:node {
                name

                members(first: 10) {
                  edges {
                    member:node {
                      name
                    }
                  }
                }
              }
            }
          }
      }
    }

    scenarios(first: 10) {
      edges {
        scenario:node {
          name
        }
      }
    }
  }
}

    Calculation:

    Code Block
    50            = 50 members (users)
 +
50 x 20       = 1,000 groups
 +
50 x 20 x 10  = 10,000 group members (users)
 +
10             = 10 scenarios

               = 10,010 total nodes

Rate limit

The GraphQL API v3 limit is different from the REST API v3's rate limits.

Why are the API rate limits different? With GraphQL, 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 Scope's servers to compute.

To accurately represent the server cost of a query, the GraphQL API v3 calculates a call's rate limit score based on a normalized scale of points. A query's score factors in first and last arguments on a parent connection and its children.

  • The formula uses the first and last arguments on a parent connection and its children to pre-calculate the potential load on Scope's systems, such as MySQL, ElasticSearch, and Git.

  • 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 v3 rate limit is 5,000 points per hour.

For Scope Apps or OAuth Apps that belong to a Scope Enterprise Cloud account, requests to resources owned by the same Scope Enterprise Cloud account have an increased limit of 15,000 points per hour.

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

Note: The current formula and rate limit are subject to change as we observe how developers use the GraphQL API v3.

Returning a call's rate limit status

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

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

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

  • The limit field returns the maximum number of points the client is permitted to consume in a 60-minute window.

  • The cost field returns the point cost for the current call that counts against the rate limit.

  • The remaining field returns the number of points remaining in the current rate limit window.)

  • The resetAt field 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 up to get the final aggregate cost. This step normalizes large numbers.

Note: The minimum cost of a call to the GraphQL API v3 is 1, representing a single request.

Here's an example query and score calculation:

Code Block
query {
  organization {
    members(first: 50) {
      edges {
        user:node {
          name

          groups(first: 20) {
            edges {
              group:node {
                name

                members(first: 10) {
                  edges {
                    member:node {
                      name
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

This query requires up to 1,011 requests to fulfill:

  • Although we're returning 50 organization members, the API has to connect to the viewer's account once to get the organization and list of users. So, requests for organization + members list = 1

  • Although we're returning 20 groups, the API has to connect to each of the 50 users to get the list of issues. So, requests for issues = 50

  • Although we're returning 10 group members, the API has to connect to each of the 200 potential total groups (50x20) to get the list of group members. So, requests for group members = 2,000

  • Total = 2,051

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