Versions Compared

Old Version 27

changes.mady.by.user David Moore

Saved on

compared with

New Version 28

changes.mady.by.user Mike Piska

Saved on

Key

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

...

Scope chose GraphQL for our API v3 because it offers significantly more flexibility for our integrators. The ability to define precisely the data you want—and only the data you want—is a powerful advantage over the REST API v2 endpoints.

If you want to get a set of data with particular properties, you don’t need to wait for a REST endpoint to be created with that data. You simply need to create a query to request that data and the GraphQL API will get it for you.

GraphQL lets you replace multiple REST requests with a single call to fetch the data you specify and all data in the system is available to you.

GraphQL Terminology

The Scope GraphQL API represents an architectural and conceptual shift from the Scope REST APIs.

...

For more information, see "Discovering the Scope GraphQL API" and reference docs. For other information, such as authentication and rate limit details, check out the guides.

Note that you may need to rely on both the docs and the real-time schema validation to successfully call the GraphQL API.

...

Node is a generic term for an object. You can look up a node directly, or you can access related nodes via a connection. If you specify a node that does not return a scalar, you must include subfields until all fields return scalars.

Discovering

...

the data the API can provide

One way to see what is available from the GraphQL API is to use the GraphQL API reference docs.

Another way is to ask it. GraphQL is introspective. This means you can ask a GraphQL schema for details about itself.

...

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.

...

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.

...

See “Reference Docs” to view reference documentation and learn about the data types available in the GraphQL API public schema. 

See “Guides” to learn how to use the Scope GraphQL Explorer to interact with the Scope GraphQL API on real data and leverage the Scope GraphQL API for a variety of tasks.