Introduction to GraphQL

Learn useful terminology and concepts related to using the Scope GraphQL API.

For more information, visit https://graphql.org/.

About GraphQL

The GraphQL data query language 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. See “Schema”.
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. See “Using Global Node IDs”.

Why Scope is using GraphQL

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. GraphQL lets you replace multiple REST requests with a single call to fetch the data you specify.

GraphQL Terminology

The Scope GraphQL API represents an architectural and conceptual shift from the Scope REST APIs. You will likely encounter some new terminology in the GraphQL API reference docs.

Schema

A schema defines a GraphQL API's type system.

It describes the complete set of possible data (objects, fields, relationships, everything) that a client can access. Calls from the client are validated and executed against the schema. A client can find information about the schema via introspection. A schema resides on the GraphQL API server. For more information, see "Discovering the Scope GraphQL API."

All calls are validated and executed against the Scope GraphQL public schema:

Allowed operations: queries and mutations.
Schema-defined types: scalars, objects, enums, interfaces, unions, and input objects.

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

For other information, such as authentication and rate limit details, check out the guides.

Field

A field is a unit of data you can retrieve from an object. As the official GraphQL docs say: "The GraphQL query language is basically about selecting fields on objects."

The official spec also says about fields:

All GraphQL operations must specify their selections down to fields which return scalar values to ensure an unambiguously shaped response.

This means that if you try to return a field that is not a scalar, schema validation will throw an error. You must add nested subfields until all fields return scalars.

Argument

An argument is a set of key-value pairs attached to a specific field. Some fields require an argument. Mutations require an input object as an argument.

Implementation

A GraphQL schema may use the term implements to define how an object inherits from an interface.

Here's a contrived example of a schema that defines interface X and object Y:

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

This means object Y requires the same fields/arguments/return types that interface X does, while adding new fields specific to object Y. (The ! means the field is required.)

In the reference docs, you'll find that:

Each object lists the interface(s) from which it inherits under Implements.
Each interface lists the objects that inherit from it under Implementations.

Connection

Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API.

It's helpful to picture a graph: dots connected by lines. The dots are nodes, the lines are edges. A connection defines a relationship between nodes.

Edge

Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every edges field has a node field and a cursor field. Cursors are used for pagination.

Node

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 Scope GraphQL API

GraphQL is introspective. This means you can query a GraphQL schema for details about itself.

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

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

Query __type to get details about any type:

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

You can also run an introspection query of the schema via a GET request:
```
$ 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.