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
curlexample 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!