This guide is designed for system administrators, and developers ready to engage with our platform API. From making your initial API requests to deep-diving into GraphQL queries, this document will guide you every step of the way.

GraphQL is an open source query language widely used to provide API access to data. See https://graphql.org/ for more information about this technology.

Making Your First API Request

Getting Started

Begin with a simple curl command to explore the first three events:

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

Don’t forget to substitute YOUR_API_TOKEN_HERE with your actual API token. and replace demo.plusplus.co with your custom domain. This is your first peek into what’s available.

Expected Response

A successful request will bring back a `200 OK` response with data similar to this:

{
  "data": {
    "events": {
      "edges": [
        {"node": {"pk": 407, "name": "Agile Training"}},
        {"node": {"pk": 408, "name": "High Output Management"}},
        {"node": {"pk": 409, "name": "Core Python"}}
      ]
    }
  }
}

This output shows each event's unique identifier (pk) and title (name).

Diving Into GraphQL

Exploring Interactively

Our interactive GraphQL playground, found at https://mycustomdomain.com/graphql, is ideal for users with Organizer or Admin roles. Use the "Docs" button to explore available queries and filters.

Important Tips:

Custom Domain: Always use your designated domain in your requests
Authorization: Access your API token via the PlusPlus app under Menu > Settings > Developers. Admin role is a must
Query Essentials: Post your query as shown in the curl example above, including the necessary headers and a JSON payload

Advanced Query Techniques

Basic Query Structure

All queries need a `first` or `last` filter to limit returned items, with a maximum of 150 items per query. For instance, to list `pk`, `name`, and `presenters` of the first 15 events:

query {
  events (first:15) {
    edges {
      node {
        pk
        name
        presenters {
          edges {
            node {
              pk
              name
            }
          }
        }
      }
    }
  }
}

Filtering Results

You can refine your queries with filters. Here’s how to filter the last 10 events with "onboarding" in their name:

query {
  events (last:10, name: "onboarding") {
    edges {
      node {
        pk
        name
      }
    }
  }
}

And to list pk, name, and starts_at for the first 5 events of 2020:

query {
  events (first:5, starts_at_after: "2020-01-01T00:00:00") {
    edges {
      node {
        pk
        name
        starts_at
      }
    }
  }
}

Mastering Pagination

For queries exceeding 150 items, pagination is your friend. Use startCursor and endCursor from the pageInfo object for navigation.

Fetching the next page of items example:

query {
  events (first:5) {
    pageInfo {
      endCursor  # Use this value in the "after" filter for subsequent queries.
    }
    edges {
      node {
        pk
      }
    }
  }
}
 
query {
  events (first:5, after: "YXJyYXljb25uZWN0aW9uOjQ=") {
    pageInfo {
      endCursor
    }
    edges {
      node {
        pk
      }
    }
  }
}

Support and Further Reading

If you run into any issues or have questions, our support team and your PlusPlus system administrator are here to help. Explore more about images, getting support, building queries, and refreshing GraphQL tokens in our additional sections.

Enjoy your journey through the powerful features of our platform!