Introduction to GraphQL

GraphQL terminology

You will probably encounter some new terminology in the Worksome GraphQL API reference docs.

Schema

A schema defines a GraphQL APIs 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 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.

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

• Query __type to get details about any type:

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

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

$ curl -H "Authorization: Bearer ${WORKSOME_API_TOKEN}" \
  https://api.worksome.com/graphql

If you get a response containing a "message": "Unauthenticated" error, check that you are using a valid token. For more information, see “Authentication.”

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 parse the results using a language-specific pretty-printer for this purpose.

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.