GraphQL Guide

Overview

GraphQL offers a relatively simple option to pull custom reports from our database by intuitively combining API-queries to different endpoints into one query. Please note, however, that the tool has a limited functionality and doesn't offer access to all endpoints availabe through direct usage of our API. For complex use cases you should still use the API directly.

Key concepts

With GraphQL developers can request exactly the data they need while avoiding over- and underfetching.

Overfetching

Requesting too much data, e.g. data from fields that are of no interest for the current use case

Underfetching

Requesting too little data (by not querying relevant API endpoints)

Get started

  • Go to our GraphQL page and enter your credentials in the "Headers" section:

{
  "authemail": "[email protected]",
  "authtoken": "tkn_74sfz84s8"
}

(Here is how to get your Token).

  • Now start building a query (e.g. for employments) by clicking on text fields you find in the huge list to the right. Those work as either
    • filters to narrow down the query or
    • output fields, that you want to see in the response.
      Initially, there are no filters and no fields in the output.
    • The minimum filters you should always use are
      • "companyID" (12345 as example)
      • "page"
      • "perPage":
    • Here is a selection of output fields ("items") that will result in employee ids and first names:
  • Your query should now look like this:
  • Click on "Try It!" to run the query, and see the results below the query box.
  • Here is another example. This query will give you a list of
    • The first 500 absences
    • with start and end times
    • together with the full name of the absence reason
    • and first name, last name and staff number of the respective employee
    • as well as an initial "count" of how many records there are in total:
query MyQuery {
  absences(state: accepted, page: 1, perPage: 500, companyId: 12345) {
    items {
      absenceReason {
        name
      }
      startsAt
      endsAt
      employment {
        firstName
        lastName
        staffNumber
      }
    }
    pagination {
      count
    }
  }
}