GraphQL

Senseye provides a GraphQL API which covers the majority of the functionality available within Senseye PdM.

GraphQL is a query language designed for APIs, it allows clients to gather many resources in a single request whilst providing just the information that is requested. The API conforms to a strongly typed schema, which acts as a contract between the client and the server.

More information about GraphQL is available on their website.

Schema¶

Senseye's GraphQL schema can be found at https://graphqldocs.senseye.io/.

Along with the root level queries and mutations, many common operations belong to hierarchy objects - the Organisation and Asset objects are good examples.

Authentication¶

Each request to the GraphQL API should include an access token within its Authorization header. For more information, please visit the Authentication documentation.

Transport¶

Senseye exposes its GraphQL endpoint via HTTP at the following URL: https://api.senseye.io/v1/graphql. This accepts POST requests with GraphQL queries encoded into the request's body as JSON. HTTP is a common way to expose GraphQL APIs and is described in more detail within the GraphQL documentation.

As an example, the following GraphQL query gathers your organization's name:

{
    organization {
        name
    }
}

this query can be executed via HTTP using the following request:

POST /v1/graphql HTTP/1.1
Host: api.senseye.io
Authorization: Bearer your_access_token
Content-Type: application/json

{"query":"{organization {name}}","variables":{}}

curl --location --request POST 'https://api.senseye.io/v1/graphql' \
--header 'Authorization: Bearer your_access_token' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{organization{name}}","variables":{}}'

The response will be of the following form:

{
    "data": {
        "organization": {
            "name": "your organization's name"
        }
    }
}

Errors¶

Unlike REST APIs, GraphQL APIs do not make use of status codes - all requests will return with a 200 status. If a request fails, the response will include an errors array, which will describe the errors which occurred. For example:

{
    "errors": [
        {
            "message": "The request failed because the failure mode was of an incorrect type.",
            "path": [
                "createWorkEvent"
            ],
            "extensions": {
                "code": "WORK_EVENT_UNEXPECTED_FAILURE_MODE",
                "errorid": "cf6c6547-4e7e-4a74-997a-5b625e99e1a7",
                "failureMode": "BAD_FAILURE_MODE"
            }
        }
    ],
    "data": {
        "createWorkEvent": null
    }
}

In the extensions object will be an errorid field. Should you need help with resolving the error, please contact support and quote the errorid reference.

The extensions object also contains a code. These codes are described in more detail here

Pagination¶

Some functions support pagination to ensure queries do not become too large. For example, cases(offset:2, limit:5) returns 5 case files starting at the third in the list. This function will also return a paginationDetails structure in its result, which includes the following information:

• total: the total number of results that are available
• count: the actual number of results that were returned in this set
• offset: the offset into the total result set
• limit: the actual limit that was used in creating the result. The API Gateway may restrict this, so it may be less than the limit requested.

To request the next page of results, you would set the offset to be offset + count, and the limit to be limit. If offset + count is greater than total then the current page is the final page.