Devices and Services

GraphQL queries and mutations for listing, creating and updating Remote.It devices and services, plus the supported application types.

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

Application Types

Application types are service type definitions which are used as parameters for Get Devices By An Attribute and in services. In the case of services only the ID is returned so you will reference this response.

query {
  applicationTypes {
   id
   name
   description
   port
   protocol
   proxy
  }
}

Response Example

{
  "data": {
    "applicationTypes": [
      {
        "id": 1,
        "name": "TCP",
        "description": "Generic TCP",
        "port": null,
        "protocol": "TCP",
        "proxy": false
      },
      {
        "id": 4,
        "name": "VNC",
        "description": "VNC remote desktop",
        "port": 5900,
        "protocol": "TCP",
        "proxy": false
      },
      ...
    ]
  }
}      

Attributes	Data Type	Description
id	Int	The primary key of the application type used in queries such as Get Devices By An Attribute
name	String	The given short name for an application type. This is unique
description	String	Further explanation of the application type
port	Int	The default port for the application type. This can be overridden on a service by service basis
protocol	String	The protocol used when creating a connection to this application type
proxy	Boolean	Whether the application type will use a reverse proxy when creating a proxy connection.

Get Your Devices

In this example we will be fetching your devices using graphQL. If you wish to get devices which meet a certain criteria like inactive devices, use the Attribute Query. Devices uses pagination for the result set. Please refer to the pagination explanation for more on working with these results.

This example only shows some of the variables and available attributes for the device and service collections.

#Query
query getDevices($size: Int, $from: Int, $sort: String) {
  login {
  # account(id:"######") {
  # use account when organization results are needed and the user credentials are not the org owner
  # org user results are based on permissions
    devices(size: $size, from: $from, sort: $sort) {
      total
      hasMore
      items {
        id
        name
        hardwareId
        created
        services {
          id
          name
        }
      }
    }
  }
  #} if org used
}
#Variables
{
  "size": 1000,
  "from": 0,
  "sort": "name",
}

Response Example

{
  "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"
              }
            ]
          },
        ...
        ]
      }
    }
  }
}    

Parameters

Parameter	Data Type	Description
size	Int	max is 1000
from	Int	Index of result set to start return. 0 based.
after	String	Device ID to use to start the return list after (used in pagination)
name	String	Filters the devices based on the string passed in (not case sensitive) Can be partial string.
application	Array of Int	Array of Application IDs. Will return only devices that have matching application type in its list of of services
hardwareId	String	Filter to return devices which have matching hardware ID. Can be a partial string
id	String	Device ID filter
platform	Array of Int	Array of Platform Type IDs. (See graphQL examples for query for Platform Types
state	String	Default is both active and inactive. Values can be "active" or "inactive"
tag	Array of Strings	Array of tag names used on devices.
owner	Boolean	true to return only owned devices. false to return only devices shared to this account (not organization devices). Default is to return both.
sort	String	attributes: name, created, id, lastReported, owner, platform, state. For ascending, use only the attribute name. For descending order, prepend the attribute name with "-". For example: sort: "-name"

Get Devices By An Attribute

In this example we will be fetching all devices with "tim" in the name using graphQL. This will return all devices with "tim" in the name and is not case sensitive. You can use any number of combinations of available attributes to narrow your result set further.

Other available parameters available:

Parameter	Data Type	Description
application	Int	ID of the application type (service type). Using this parameter will return devices which have services of a given type and if the services are returned in the query will only include the services of this type. For example, if you request an application type id which is mapped to SSH and include the services, only services of type of SSH will be returned in the services array even when there are other services defined on the device. To get available service types, please see Application Types
hardwareid	String	The hardware ID associated with the device.
name	String	String which is present in the name of the device and is not case sensitive.
platform	[Int]	Array of platform IDs
state	String	accepted values "active" and "inactive"

Additional attributes will become available over time. Please refer to the schema documentation for the extensive list.

This example only shows some of the variables and available attributes for the device and service collections.

#Query
query getDevices($size: Int, $from: Int, $sort: String, $state: String, $name: String) {
  login {
    devices(size: $size, from: $from, sort: $sort, state: $state, name: $name) {
      total
      hasMore
      items {
        id
        name
        hardwareId
        created
        services {
          id
          name
        }
      }
    }
  }
}
#Variables
{
  "size": 1000,
  "from": 0,
  "sort": "name",
  "state": "inactive",
  "name": "tim"
}

Once you get the results, if the hasMore response returns true you know to do another fetch and 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.

Response Example

{
  "data": {
    "login": {
      "devices": {
        "total": 1200,
        "hasMore": true,
        "items": [
          {
            "id": "8X:XX:XX:00:29:01:8e:ed",
            "name": "Bento Time Machine",
            "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"
              }
            ]
          },
        ...
        ]
      }
    }
  }
}    

Update a Device/Service Name

Only the owner of the device or an admin on the organization owning the device can update the name of the device or service.

Parameters	Data Type	Description
serviceId	String	This is the device Id or service Id that will be updated
name	String	The new name of the device or service

mutation {
  renameService(
    serviceId: "80:00:00:01:23:45:67:89",
    name: "New Name"
  )
}

Query Response

{
  "data": {
    "renameService": true
  }
}

Update a Device or Service

Only the owner of the device or an admin on the organization owning the device can update a device.

Parameter	Data Type	Description
serviceId	String!	Required - The device Id or service Id that will be updated
refresh	Boolean!	Boolean to send the updates to the device. This should be true to push the updated configuration to the device.
enabled	Boolean	Configuration for the remoteit daemon on a service. It must be true to enable connections and online/offline state. Can be set to false if you would like to disable the service to reduce network ping traffic.
application	Int	ID of the application type (service type). Using this parameter will return devices which have services of a given type and if the services are returned in the query will only include the services of this type. For example, if you request an application type id which is mapped to SSH and include the services, only services of type of SSH will be returned in the services array even when there are other services defined on the device. To get available service types, please see Application Types
name	String	The name of the device or service
host	String	Default is 127.0.0.1 (localhost) if the service runs locally on the device, if null it is treated like localhost. OR The local network IP address or fully qualified domain name to configure this as a jump service to a system on your local network.
port	String	The port for this service on the device. (Leave null for the Device) For example, SSH is 22 unless configured differently on your device

mutation {
    updateDevice(
     deviceId: "80:00:00:98:01:23:45:67",
     refresh: true,
     name: "New Name",
     port: 22
    )
}

Query Response

{
  "data": {
    "updateDevice": true
  }
}

Delete Device

Only the owner of the device or an admin on the organization owning the device can delete a device. Devices can only be deleted when the state is inactive.

mutation {
  deleteDevice(
    deviceId: "80:00:00:98:01:23:45:67"
  )
}

Query Response

{
  "data": {
    "deleteDevice": true
  }
}

Remove a Service

Only the owner of the device or an admin on the organization owning the device can remove a service from a device.

Services will be removed even if active and in use

mutation {
  removeService(
    id:"80:00:00:98:01:23:45:67"
    )
}

Query Response

{
  "data": {
    "removeService": true
  }
}