GraphQL Subscriptions

The Cynox IoT GraphQL API supports the GraphQL over WebSocket protocol for subscriptions. The project website offers various recipes to get started using your favorite programming language.

Authorization

Authorization for subscriptions works analogous to normal GraphQL HTTP requests, however the Authorization value must be passed via the connection init payload instead:

JavaScript (graphql-ws)

Using GraphQL WS

import { createClient } from 'graphql-ws';
const client = createClient({
    connectionParams: {
        Authorization: `Bearer ${token}`,
    },
});

Python (GQL)

Using GQL 3

from gql import Client
from gql.transport.websockets import WebsocketsTransport

transport = WebsocketsTransport(
    init_payload={
         'Authorization': f'Bearer {token}'
    }
)
client = Client(transport=transport)

The deviceUpdates subscription

The GraphQL API offers device and other updates via the deviceUpdates subscription.

Device update types

You can choose which type of changes you want to subscribe to via the DeviceUpdateType enum.

• COMMANDS: Information about new or updated commands for this device
• METADATA: The device’s metadata (such as its label) was changed
• REPORT: A new report is available from the device, such as an energy reading or the current switch state.
• STATUS: The device’s status has changed, such as the device encountering an error or the device coming online. You can get the updated status by querying the device’s status field.

Now you can subscribe to updates for a device using the deviceUpdates subscription. In this example we’re listening for new or updated commands for a device.

subscription deviceUpdates($deviceId: GlobalID!) {
  deviceUpdates(deviceId: [$deviceId], updateTypes: [COMMANDS]) {
    __typename
    ...on DeviceUpdateBase {
      deviceId
    }
    ... on DeviceCommandUpdate {
      commandId
    }
  }
}

When any command for the requested devices changes, you will now be notified via this subscription like so:

{
    "deviceUpdates": {
      "__typename": "DeviceCommandUpdate",
      "deviceId": "U29ja2V0TWFzdGVyOmM0MzI2OTBhLTFkMjAtNDU1MS04M2E3LTUyYTU1ZWRmYmQ3NQ==",
      "commandId": "U29ja2V0TWFzdGVyU2V0U3dpdGNoU3RhdGVDb21tYW5kOmM0MzI2OTBhLTFkMjAtNDU1MS04M2E3LTUyYTU1ZWRmYmQ3NQ=="
    }
}

You can then reload the changed command with the node query:

query updateCommand($commandId: GlobalID!) {
  node(id: $commandId) {
    ...on DeviceCommand {
      __typename
      executionState
    }
    ...on SocketMasterSetSwitchStateCommand {
      switchState
    }
  }
}

For a response example see section polling command information.