GraphQL overview

Unlike REST APIs, where there is a clearly defined structure of information returned from each endpoint, GraphQL always exposes one endpoint, allowing you to determine the structure of the data that is returned.

The result of each query will be formatted in the same way as the query itself.

In the following section, we'll take a quick look at GraphQL components.

For a deep dive into what you can do with GraphQL, check out the GraphQL Foundation's Introduction.

Operations

Query

A GraphQL query performs the READ operation and does not change data.

Mutation

To perform all other operations to modify data you will need mutations. You can think of mutations as CUD (Create, Update, Delete) in REST.

Object types

Object types are a collection of fields, which are used to describe the set of possible data you can query from the API.

Fields

Fields are used to ask for specific properties in objects.

Each object has fields that can be queried by name in order to query for specific properties.

Arguments

You can pass arguments to a query to determine the return value (e.g. filtering search results) and narrow down the results to the specific ones you’re looking for.

Playground

One of the most powerful aspects of GraphQL is its visual interface. GraphQL Playground is an in-browser tool for writing, validating, and testing GraphQL queries.

Before diving in and starting querying the API, it’s highly recommended to run your queries through the visual interface to make sure they're correct and the data being returned is the data you expect.

Accessing Playground

Variables

Variables can be used to pass dynamic values to our arguments. Variables are written outside of the query string itself in the variables section, and passed to the arguments.

When we start working with variables, we need to do three things:

• Replace the static value in the query with $variableName.

• Declare $variableName as one of the variables accepted by the query.

• Pass variableName: value in the separate, transport-specific (usually JSON) variables dictionary.