This article is best for system administrators, engineers, and developers. Too small? Click here.

Quickstart

Sample curl request:

curl -H "Authorization: Token " \     
     -H "Content-Type: application/json" \     
     -d '{"query":"{events(first:3){edges{node{pk name}}}}"}"}' \         
     -X POST  https://demo.plusplus.co/graphql

Response:

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
{
  "data": {
    "events": {
      "edges": [
        {
          "node": {
            "pk": 407,
            "name": "Agile Training"
          }
        },
        {
          "node": {
            "pk": 408,
            "name": "High Output Management"
          }
        },
        {
          "node": {
            "pk": 409,
            "name": "Core Python"
          }
        }
      ]
    }
  }
}

GraphQL Interactive

To test and play queries to the GraphQL API you can use the interactive interface. It is available to users with Organizer and Admin role at the URL https://mycustomdomain.com/graphql. There you will find a “Docs” button at the to right corner of the page where it’s possible to click through the available resources and fields. Also, pay attention to the filters available to each node.

HOST URL

Always use your custom domain as the HOST of your requests.

Eg.: https://mycustomdomain.com/graphql

Authorization

Get your API token from within the PlusPlus app via Menu > Settings > Developers.

You need to have Admin role.

Authentication is done via the Authorization HTTP header. It should be in the following format:

Authorization: Token {your-api-token}

Notice the word Token before the token value.

Making Queries

To query GraqhQL APIs you will make a POST request to the GraphQL endpoint with the Authorization and Content-Type headers (as shown in the curl example above) and a body with a JSON payload in the following format:

{
  "query": "{ events(first: 3) { edges { node { pk name }}}}"
}

Notice the string in the query field is the query you would build using the GraphQL Interactive interface.

Important

We recommend using a GraphQL client in the language of your choice to make the requests. They will help you exploring, debugging and testing your application. The official GraphQL website has a list of available clients in many different programming languages: https://graphql.org/code/#graphql-clients.

Resource Lists

Lists of items will always be presented in the structure:

resource { edges { node }}

When requesting a list of items it will be mandatory to specify the maximum number of items to be returned either using the first or last parameter. The maximum number of items per page is 300.

Filtering

Filters are parameters just like first and after. Use the interactive explorer Docs to find out about which are the available filters for a given resource.

List filters

Some filter parameters allow passing a list of items. Passing more than one item will result in a OR query. Eg.:

query {
  events(first: 2, presenter_id: [10, 32])
    edges {
      node {
        pk
        name
      }
    }
  }
}

The above query will return all the events where at least one presenter is the user with the id 10 or the user with id 32.

Filtering Deleted Items

By default non filtered queries will return all items including deleted ones. You can remove those by filtering them out. To the date of publication of this document all types have a is_deleted field and a is_deleted filter. Eg.:

query { events(first: 2, is_deleted: false) edges { node { pk name } } } }

Pagination

Use the pageInfo attribute to get paging information. E.g.:

query { events(first: 2) { pageInfo { hasNextPage endCursor } edges { node { pk name } } } }

Will return:

{ "data": { "events": { "pageInfo": { "hasNextPage": true, "endCursor": "YXJyYXljb25uZWN0aW9uOjE=" }, "edges": [ { "node": { "pk": 407, "name": "Agile Training" } }, { "node": { "pk": 408, "name": "High Output Management" } } ] } } }

You can then use the endCursor to fetch the next page:

query { events(first: 2, after: "YXJyYXljb25uZWN0aW9uOjE=") { pageInfo { hasNextPage endCursor } edges { node { pk name } } } }

Formats

Datetime

Datetimes will always be presented using the timezone aware ISO8601 format. E.g.: “2018-05-07T12:00:00-07:00”.

More Examples

You can find more query examples in this article.

Sample Python code

import requests


token = "{your-token-here}"
query = """{
  events(first: 300, is_deleted: false) {
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      node {
        event_type {
          name
          pk
        }
        name
        pk
      }
    }
  }
}"""

response = requests.post(
    "{your-domain}/graphql", 
    json={"query": query}, 
    headers={
        "Authorization": f"Token {token}",
    }
)

data = response.json()

Images

All image URLs returned by GraphQL queries are signed and have an expiration time of 7 days. This is a limitation imposed by our file storage provider AWS S3 and cannot be increased.

Support

In case you have any problems, need help or need any information that is not yet available in the GraphQL API, please contact your PlusPlus system administrator or PlusPlus Support.