About GraphQL

If you are new to GraphQL, you should take some time to familiarize yourself with some basic GraphQL concepts before digging into our documentation. For a quick introduction, see the Basic Concepts section below. To get more in-depth, there are many great resources to learn GraphQL — to start with, we recommend Introduction to GraphQL and How to GraphQL.

If you're already comfortable with GraphQL, feel free to skip ahead and begin learning about the Payments API or making API calls.

Basic Concepts

Queries and Mutations

GraphQL requests come in two forms: queries and mutations. Queries are used to fetch data from the remote API (like a GET in a REST API). Mutations are used to make a change (like a PUT or a POST in a REST API). Both queries and mutations can take inputs.

In its simplest form, each request starts with the keyword query or mutation, then specifies the field or fields you want to get back in the response.

query {
  ping
}

The name of the field being requested is ping, and it is of type String, so it doesn't have any subfields. This is exactly what you'll receive back in the response.

"data": {
  "ping": "pong"
},

You can see this query and all others in action in the API Explorer.

In these guides, you'll also frequently see operations given a name, such as:

query ExamplePingQuery {
  ping
}

This just serves as a kind of label for the query or mutation, and can be whatever you want.

Schema and Types

To find out what queries and mutations are allowed in a GraphQL API, what they do, and what they return, you can consult its schema. The schema defines and documents all types available in the API. This is possible because everything in a GraphQL API is strongly typed — including queries and mutations, plus their inputs and payloads.

GraphQL supports introspection queries for getting information about the API you're using: you can create a GraphQL query to tell you everything about the schema.

For example, this GraphQL query:

query {
  __schema {
    types {
      name
      description
    }
  }
}

will return every type in the schema.

Using the schema, you can validate the exact composition of all your requests, and know ahead of time exactly what you'll get back. Since the schema is part of the API, it is always up-to-date. It will be your primary point of reference when developing against the API.

The API Explorer

You can take a look at the Braintree API schema and try out queries and mutations with the API Explorer. Dive in now or read more about using it in the rest of these guides.

Relay

The Braintree GraphQL API also implements the Relay specification, which defines a few features on top of the GraphQL specs. If you're using the Relay framework, the Braintree API is compatible with it. This is primarily relevant for looking up objects and searching.