Skip to content

General Information

These APIs should be considered under construction. We are working hard to bring you all of the features you need, and will roll those features out as we have them available.

Why GraphQL?

It would be hard to state the case for GraphQL better than the official GraphQL Website, but here is the most relevant piece:

GraphQL provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

We know that the technicians using your software are out in the real world helping real people with real problems, and we want to make sure our API ultimately helps them get their work done without getting in the way. We believe that GraphQL helps us to achieve that aim.

How to Use Examples

There are a number of examples provided throughout this site. We have taken those examples and pre-loaded them into workspace that can be imported into the Insomnia REST/GraphQL testing tool. A link is provided below to a page that includes a download of that pre-packaged workspace. That same page provides links for downloading Insomnia. The tool is free, and we have been quite satisifed with its clean interface.

Run in Insomnia

See the Insomnia Details guide for more information regarding Insomnia and the provided examples workspace.

IMPORTANT NOTE: When updating from one version of the Insomnia examples to the next, please be sure to compare any private environments you have set up with the Environment TEMPLATE provided in the update. Add any new values to your private environments as new request examples may depend on those values.

If you prefer command line tools, we have built a simple bash script you can download here. The examples provided in the various guides in this site can be inserted into that script for further experimentation.

There are some values you will need to update in that bash script. Those details, as well as information on running the script, are in the script itself.

How to Determine Success or Failure of a Request

The response that you see will either have one of two top-level keys. If the request was successful, you will have a data key. If the call was not successful, you will instead have an errors key.

In the success case, the results of your query or mutation will be included in the top-level data object, under a key that corresponds to the name of the query or mutation. In the error case, the errors key will contain an array of error objects. Each error will provide an errorType and a message.

For example, a successful response will begin as follows:

{
  "data": {
    "getJob": {
      "job": {
        "id": "B819-D69C6E8DE8354AADB88A4121DDC70AF4",
        ...response continues...

Alternatively, an error would look more like this:

{
  "data": null,
  "errors": [
    {
      "errorType": "NotFound",
      ...response continues...