API Usage

eid (external ID)

Most entities have a field called eid, which is a unique identifier amongst entities of the same type and will not change as long as the underlying entity exists. You can use it to reference an entity directly in some queries.

Example

query {
  device(input: { eid: "<deviceEid>" }) {
    device {
      eid
    }
  }
}

You can find out the eid of an entity

• after creating it
• by querying a list of available entities of a certain type, e.g. device

Pagination

info

• If you don't provide any pagination instructions, 5 items will be returned per page by default.
• You can only fetch a maximum of 100 items per page.

We are using cursor-based pagination, which means that a cursor is used to keep track of where in the data set the next items should be fetched from. The cursor can contain various information like the index of the record within the set and properties that the server can use to recreate the set.

query {
  devices(first: 10) {
    totalCount
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    nodes {
      eid
      name
      manufacturer
    }
  }
}

This query will fetch the first 10 devices that the user has access to. With the information returned from this query, another query can be built to fetch the next page, i.e. the next 10 results in the pagination.

• totalCount: the total amount of objects available in this query
• pageInfo: information about the current page of the pagination
  • startCursor: the cursor of the first item on the page
  • endCursor: the cursor of the last item on the page
  • hasPreviousPage: true if there is a page before the current one, false otherwise
  • hasNextPage: true if there is a page after the current one, false otherwise
• nodes: the actual objects that are being queried
  • You can query all fields that belong to the queried type here

There is also an additional property not listed in the example above:

• edges: lists every object in the response, including its pagination cursor

In the example above, we are fetching the first 10 devices, but there are other options:

• last: <amount>: fetch the last items in the pagination result
• after: "<cursor>": fetch the pagination results that start after the given cursor
• before: "<cursor>": fetch the pagination results that end before the given cursor

Simple example how to fetch all pages of a query

• Use the above query to fetch the first 10 devices. This is the first page of the pagination.
• If the response for hasNextPage is true, then you can continue with the next step.
• Construct another query based on the previous one, but instead do the following:
  • Get the cursor for the last item on page 1, which is stored in endCursor, and use it in the query: devices(first: 10, after: "<endCursor>") { … }
  • You will now get the second page of the pagination
• Continue like this until you hit hasNextPage = false

Sorting & Filtering

For many queries we offer the ability to sort and filter certain fields. Here is an example:

{
  devices(
    first: 10
    order: { name: DESC }
    where: { serialNumber: { contains: "1" } }
  ) {
    nodes {
      name
      serialNumber
    }
  }
}

This query will return

• the first 10 devices
• ordered by their name in descending order
• where the serial number of the device contains the string “1”

Some more examples:

• Ordering by date values: order: { lastContact: DESC }
• Ordering by multiple fields: order: { name: DESC, lastUpdatedAt: ASC }
• Filtering by multiple fields: where: { and: [{ serialNumber: { contains: "1" }, status: { eq: ACTIVE } }] }
  • you can also use or: instead of and:

caution

We recommend to always add at least an order statement in your queries, as the order of the results can’t be guaranteed otherwise. For example, changing an index in our database might change the order in which results are returned.