Usage

remote.it is in the process of making available all functions in graphQL and will be eventually deprecate the REST-API. This documentation provides the REST-API where the function is not available via graphQL.

Remote.it Insomnia Collection

We have developed an example set of GraphQL queries and mutations in a collection that you can import directly into insomnia to get started. You will still need to install the authentication plug-in here and create your access keys in your account before getting started.

$ git clone https://github.com/remoteit/code_samples.git

What is GraphQL?

GraphQL is a data query language for API's, developed by Facebook in 2012 before being publicly released in 2015. GraphQL provides an alternative to the REST API.

For more information on GraphQL, learn on the official GraphQL website here.

How to Access GraphQL

https://api.remote.it/graphql/v1 Continue through this documentation to learn about our schema and some useful examples.

remote.it authentication uses HTTP Request Signature; more on Authentication can be found here.

GraphQL Clients (Developer Tools)

These are some of the most popular developer tools used with GraphQL API's which you can use to explore the schema.

• Insomnia

• Postman

• GraphiQL

• Altair

We provide some basic setup and usage for the Insomnia client here.

You can view our visual schema reference here.

Schema Definitions

GraphQL endpoint supports introspection queries via the __schema query. There is also a visual version of the schema available at https://api.remote.it/v1/graphql/doc

We recommend using a GraphQL client (Developer Tools) to introspect and explore the schema.

Configure your GraphQL client to use the API endpoint:

https://api.remote.it/graphql/v1

Schema convention is to use upper camel case for object types and lower camel case for property names.

Note that these objects and parameters are continually enhanced. Please use your IDE for the most up to date schema. The changes are designed to be non-breaking by adding rather than deleting or changing existing definitions.

Basic types are:

• ID (similar to the string type but used for object IDs)

• String

• Int

• Float

• Boolean

• DateTime (ISO 8601 format Date String)

Queries

Queries are requests which read the data and will not change the data. All queries will be in context of the user associated with the access key and secret. The usage examples include a variable section which will need to accompany the query or alternatively, you can put the values inline.

Fetching updates

If you're working on building an application which display data and you want the status information to update (near) realtime, use the webhook. To prevent excessive usage of our API, we recommend that you be mindful about your implementation.

Do's:

• Register a programmatic webhook and get updates for status changes on your devices. When you detect changes, update the device information

Dont's:

• Poll updates for each device. There should never be a reason to do this, unless in small cases and your application might get rate limited. See above tactics to implement this better.

Mutations

Mutations are requests which update data. All mutations are in context of the user associated with the access key and secret.

In the case where we do not have the functionality supported, the REST-API examples are provided. These will be updated from time to time as remote.it migrates to support graphQL only.

Pagination

The list responses from the devices and event log queries return paginated results. We implement a pagination model with from/after and size pagination arguments. Responses can return hasMore, last and total . If the hasMore response returns true, this indicates do another fetch. In this case, the from will increment to 1001 to fetch the next set. You could also determine this by iteration until you get to the total. Size is limited to 1000 max in each return.

Filter

Attribute	Data Type	Description
size	Int	Number of records to return in result of items (Max value is 1000)
from	Int	Where to start return of list if there are more records than the size
last	String	Primary ID of the item returned to start in the return (If this is passed, from is ignored, however it may not return if the rest of the filters to not include this item)
sort	String	attribute to sort the item list return and append a space + asc or desc for ascending and descending
additional filters are available per collection		See documentation in Schema for complete list as this is updated.

#Query

query getDevices($size: Int, $from: Int, $sort: String) {
  login {
    devices(size: $size, from: $from, sort: $sort) {
      total
      hasMore
      last
      items {
        id
        name
        hardwareId
        created
        services {
          id
          name
        }
      }
    }
  }
}

#Variables
{
  "size": 1000,
  "from": 0,
  "sort": 'name',
}

Result Response

{
  "data": {
    "login": {
      "devices": {
        "total": 1200,
        "hasMore": true,
        "items": [
          {
            "id": "8X:XX:XX:00:29:01:8e:ed",
            "name": "bento",
            "hardwareId": "dc:a6:32:19:8b:a3-xWoYf46uJ6QdtPXTloLb",
            "created": "2019-12-20T22:13:46.000Z",
            "services": [
              {
                "id": "8X:XX:XX:00:29:01:8e:ed",
                "name": "ssh service"
              }
            ]
          },
        ...
        ]
      }
    }
  }
}    

Response List Attribute

Attribute	Data Type	Description
total	Int	Number of records that exist based on the filter criteria of query
hasMore	Boolean	Indicates if you should make an additional request to fetch more records if you want the full list
last	String	ID of the last item in the returned list.