Introduction to GraphQL

GraphQL terminology

The Worlds GraphQL API represents the rich ecosystem and relationships between the objects within the Worlds system. 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 GraphQL API.”

Field

A field is a unit of data you can retrieve from a node, or 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.

Connection

Connections let you query related objects as part of the same call. Connections often allow for filtering and pagination, and can connect nested objects in helpful ways to reduce the number of requests to the GraphQL 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 by providing access to the set of edges.

For more information, see “About queries.”

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. For more information, see “About queries.”

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 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
        fields {
          name
        }
        inputFields {
          name
        }
        enumValues {
          name
        }
      }
    }
  }

• Query __type to get details about any type:

  query {
    __type(name: "EventProducer") {
      name
      kind
      fields {
        name
      }
    }
  }

You may test these queries on the GraphiQL Explorer once you have the necessary authentication credentials.