GraphQL API

The Warhorn API is built on GraphQL, a strongly-typed, hierarchical query language designed for APIs. With GraphQL, you define precisely the data that you want within a single query. No need to stitch together data from multiple REST requests.

The API’s schema defines the complete set of possible data that a client can access. Calls from the client are validated and executed against the schema.

How it works

As the developer of a website or app that will use the Warhorn API, you’ll do the following:

  1. Register your application in your Warhorn account settings.
  2. Obtain an access token. You can do this in one or both of the following ways:
    • Implement Warhorn Login in your app. When a user logs into your app using Warhorn Login, the app will receive a user token authorizing it to make API requests on the user’s behalf.
    • Locate your app token in your Warhorn account settings and implement your app to use it. Note that app tokens have many fewer permissions than user tokens; which type you use will depend on your use case. See the access token document for more information.
  3. Send GraphQL API requests from your app to the GraphQL API endpoint, including either an app token or a user token.

Using the API

GraphQL operations are either queries (read operations) or mutations (write operations). The set of available operations are defined in the API schema.

You can explore the Warhorn GraphQL schema using the GraphQL explorer.

You can download the schema in IDL or JSON format using the get-graphql-schema tool (or something similar):

$ get-graphql-schema https://warhorn.net/graphql > schema.graphql

GraphQL queries

A sample GraphQL query looks like:

query($slug: String!) {
  event(slug: $slug) {
    registrations {
      nodes {
        registrant {
          activationState
          email
          name
        }
      }
    }
  }
}

This is a parametered query that relies on a string-typed variable named slug being present in the request. The GraphQL engine translates this query into a database look for the event uniquely identified by the given slug and returns that event’s registrations, including the activation state, email address and name for each registrant.

GraphQL queries only return the data you specify in the query. Even if the event, registration or registrant types define fields other than the ones listed in this query, only these specific fields will be returned for this query.

GraphQL variables

Variables allow you to make queries dynamic by parameterizing them. Variables are specified separately in an API request body from the query (see the sample API request below). Thus, your app can specify a different variable value on each request while keeping the query the same each time.

GraphQL mutations

The Warhorn API does not yet support mutations.

Token authentication

Your app must authenticate any API request by providing an access token. The Authorization request header is used for this purpose, as defined by the OAuth 2.0 Bearer Token Usage specification (RFC6750).

API request

Regardless of operation type, the API consists of an HTTP POST request with a JSON-encoded body.

A sample query request looks like (substituting the above query string for <QUERY>):

POST /graphql HTTP/1.1
Host: warhorn.net
Authorization: Bearer y1XX8rsAPrEfdk4GBAXZH2TL
Content-Type: application/json
Accept: application/json

{"query":"<QUERY>","variables":{"slug":"bionic-dwarf"}}

The corresponding response looks like (with JSON pretty-printed):

200 OK
Cache-Control: max-age=0, private, must-revalidate
Content-Type: application/json; charset=utf-8

{
  "data": {
    "event": {
      "registrations": {
        "nodes": [
          {
            "registrant": {
              "activationState": "active",
              "email": null,
              "name": "Flux Capacitor"
            }
          },
          {
            "registrant": {
              "activationState": "active",
              "email": "bcm@warhorn.net",
              "name":"Brian Moseley"
            }
          }
        ]
      }
    }
  }
}

Configuration

API endpoint
https://warhorn.net/graphql

Reference

graphql.org is your one-stop shop for learning how to use GraphQL.