SNAP Thing Services API
SNAP Thing Services API Version 1.5.0
Account ¶
Handles requests for the /changePassword resource path ¶
Update password for currently authenticated userPOST/api/v1/changePassword
Password complexity rules are enforced when changing the user’s password; the new password must be at least 8 characters long and include a combination of lower and uppercase letters, numbers, and symbols.
Example URI
POST /api/v1/changePassword
Request
Body
{
"new": "yourNewPassword1#",
"old": "yourOldPassword"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Update device",
"description": "A device",
"properties": {
"new": {
"pattern_description": "Password must be at least 8 characters and include a combination of lower and uppercase letters, numbers, and symbols.",
"pattern": "^(?=.*[0-9])(?=.*[!@#$%^&*_\\-])(?=.*?[a-z])(?=.*?[A-Z])[a-zA-Z0-9!@#$%^&*_\\-]{8,}$",
"description": "New password",
"type": "string"
},
"old": {
"description": "Old password",
"type": "string"
}
},
"required": [
"old",
"new"
],
"type": "object"
}Response
200Body
{
"data": "Successfully changed password"
}Schema
{
"properties": {
"data": {
"type": "string"
}
},
"type": "object"
}Response
400The password could not be changed for any number of reasons (e.g. the old password was incorrect, or the new password does not meet the complexity requirements). The message property of the response should indicate the reason for the failure.
Body
{
"error": {
"message": {
"new": "Password must be at least 8 characters and include a combination of lower and uppercase letters, numbers, and symbols."
}
}
}Schema
{
"properties": {
"error": {
"message": {
"type": "string"
},
"type": "object"
}
},
"type": "object"
}Administration ¶
Backup ¶
Backup databaseGET/api/v1/backup
Create a backup of the current synapse-network-service database
Example URI
GET /api/v1/backup
Response
200Body
"Backup file: synapse-network-service.sqlite"Response
400The database could not be backed up
Body
{
"error": {
"message": "Unable to backup the database. Please check the server logs for more information."
}
}Schema
{
"properties": {
"error": {
"message": {
"type": "string"
},
"type": "object"
}
},
"type": "object"
}Configuration ¶
Network ¶
Handles requests for the /network resource path.
Get the current network settingsGET/api/v1/network
Example URI
GET /api/v1/network
Response
200Body
{
"data": {
"configured_settings": {
"channel": 10,
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"rpcCrc": false,
"networkId": "0x3ab3",
"packetCrc": true,
"encryptionType": "AES-128"
},
"actual_settings": {
"channel": 10,
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"rpcCrc": false,
"networkId": "0x3ab3",
"packetCrc": true,
"encryptionType": "AES-128"
},
"bridge_addr": "012345"
}
}Schema
{
"properties": {
"apiVersion": {
"type": "string"
},
"data": {
"properties": {
"configured_settings": {
"description": "Configured network settings",
"properties": {
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check should be enabled",
"type": "boolean"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation should be enabled",
"type": "boolean"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
}
},
"type": "object"
},
"actual_settings": {
"description": "Actual bridge node network settings",
"properties": {
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check is enabled",
"type": "boolean"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation is enabled",
"type": "boolean"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
}
},
"type": "object"
},
"bridge_addr": {
"description": "Device MAC Address",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Could not get network settings.
Body
{
"error": {
"code": 400,
"message": "Could not get network settings"
},
"apiVersion": "v1"
}Schema
{
"properties": {
"error": {
"properties": {
"code": {
"description": "HTTP response status",
"type": "integer"
},
"message": {
"type": "string"
}
},
"type": "object"
},
"apiVersion": {
"type": "string"
}
},
"type": "object"
}Update the current network settingsPUT/api/v1/network
Example URI
PUT /api/v1/network
Request
Body
{
"channel": 10,
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"rpcCrc": false,
"networkId": "0x3ab3",
"packetCrc": true,
"encryptionType": "AES-128"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Update network settings",
"description": "A group of network settings",
"properties": {
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check should be enabled",
"type": "boolean"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation should be enabled",
"type": "boolean"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
}
},
"required": [
"channel",
"networkId",
"rpcCrc",
"packetCrc",
"encryptionType",
"encryptionKey"
],
"type": "object"
}Response
200Headers
Content-Type: application/jsonBody
{
"apiVersion": "v1",
"data": {
"channel": 10,
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"rpcCrc": false,
"networkId": "0x3ab3",
"packetCrc": true,
"encryptionType": "AES-128"
}
}Schema
{
"properties": {
"apiVersion": {
"type": "string"
},
"data": {
"properties": {
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check is enabled",
"type": "boolean"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation is enabled",
"type": "boolean"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Could not update network settings.
Body
{
"error": {
"code": 400,
"message": "Could not update network settings"
},
"apiVersion": "v1"
}Schema
{
"properties": {
"error": {
"properties": {
"code": {
"description": "HTTP response status",
"type": "integer"
},
"message": {
"type": "string"
}
},
"type": "object"
},
"apiVersion": {
"type": "string"
}
},
"type": "object"
}Data Collector ¶
Data Collector Collection ¶
Get the list of data collectorsGET/api/v1/dc
Example URI
GET /api/v1/dc
Response
200Returns the array of previously created data collectors.
Headers
Content-Type: application/jsonBody
{
"data": [
{
"initRpcName": "setReceiverAddress",
"href": "https://localhost:3000/api/v1/dc/dc1",
"name": "dc1",
"data_collector_type": "asynchronous",
"dataRpcName": "acceptData",
"deviceTypes": [
"sensors"
],
"id": 1
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Create a data collectorPOST/api/v1/dc
Example URI
POST /api/v1/dc
Request
Body
{
"deviceTypes": [
"sensors"
],
"queryFunction": "data",
"pollInterval": 60,
"name": "dc1",
"dataCollectorType": "synchronous"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Add data collector",
"description": "A data collector",
"properties": {
"initRpcName": {
"anyOf": [
{
"pattern_description": "Init functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"description": "Name of function implemented by SNAPpy script (required for async only)",
"type": "string"
},
{
"type": "null"
}
]
},
"dataRpcName": {
"pattern_description": "Data functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"description": "Name of the RPC that the receiver will listen on for new data (required for async only)",
"type": "string"
},
"queryFunction": {
"pattern_description": "Query functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"description": "Name of query function (required for sync only)",
"type": "string"
},
"name": {
"pattern_description": "Data collector names must be letters, numbers, underscores, periods, and dashes. (ex: 'dc1', 'Data_Collector.1-b')",
"pattern": "^[A-z0-9_.-]+$",
"description": "Name of data collector",
"type": "string"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"pollInterval": {
"minimum": 5,
"maximum": 86400,
"description": "Number of seconds between polls (required for sync only)",
"type": "integer"
}
},
"required": [
"name",
"deviceTypes"
],
"type": "object"
}Response
201The data collector was successfully created.
Body
{
"data": {
"initRpcName": "setReceiverAddress",
"href": "https://localhost:3000/api/v1/dc/dc1",
"name": "dc1",
"dataRpcName": "acceptData",
"dataCollectorType": "asynchronous",
"deviceTypes": [
"sensors"
],
"id": 1
}
}Schema
{
"properties": {
"data": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}Response
409A data collector with this name already exists.
Body
{
"error": {
"message": "A data collector with this name already exists"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
400A data collector could not be added with these attributes.
Body
{
"error": {
"message": "A data collector could not be added with these attributes"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Data Collector ¶
Delete a data collectorDELETE/api/v1/dc/{name}
Example URI
DELETE /api/v1/dc/dc1
URI Parameters
- name
string(required) Example: dc1Name of a data collector
Response
204The data collector was successfully deleted.
Response
404No data collector found for this identifier.
Body
{
"error": {
"message": "Data collector could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Data Collector Configuration ¶
Get a single data collector's configurationGET/api/v1/dc/{name}/config
Example URI
GET /api/v1/dc/dc1/config
URI Parameters
- name
string(required) Example: dc1Name of a data collector
Response
200Returns the configuration for the data collector with this name
Headers
Content-Type: application/jsonBody
{
"data": {
"href": "https://localhost:3000/api/v1/dc/dc1",
"queryFunction": "data",
"name": "dc1",
"dataCollectorType": "synchronous",
"deviceTypes": [
"sensors"
],
"id": 1,
"pollInterval": 60
}
}Schema
{
"properties": {
"data": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}Update a single data collectorPUT/api/v1/dc/{name}/config
Example URI
PUT /api/v1/dc/dc1/config
URI Parameters
- name
string(required) Example: dc1Name of a data collector
Request
Body
{
"dataRpcName": "acceptData",
"deviceTypes": [
"sensors"
],
"initRpcName": "setReceiverAddress",
"name": "dc1",
"dataCollectorType": "asynchronous"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Update a data collector",
"properties": {
"initRpcName": {
"anyOf": [
{
"pattern_description": "Init functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"description": "Name of function implemented by SNAPpy script (required for async only)",
"type": "string"
},
{
"type": "null"
}
]
},
"dataRpcName": {
"pattern_description": "Data functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"description": "Name of the RPC that the receiver will listen on for new data (required for async only)",
"type": "string"
},
"queryFunction": {
"pattern_description": "Query functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"description": "Name of query function (required for sync only)",
"type": "string"
},
"name": {
"pattern_description": "Data collector names must be letters, numbers, underscores, periods, and dashes. (ex: 'dc1', 'Data_Collector.1-b')",
"pattern": "^[A-z0-9_.-]+$",
"description": "Name of data collector",
"type": "string"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"pollInterval": {
"minimum": 5,
"maximum": 86400,
"description": "Number of seconds between polls (required for sync only)",
"type": "integer"
}
},
"description": "A data collector",
"type": "object"
}Response
200The data collector was successfully updated.
Body
{
"data": {
"initRpcName": "setReceiverAddress",
"href": "https://localhost:3000/api/v1/dc/dc1",
"name": "dc1",
"dataRpcName": "acceptData",
"dataCollectorType": "asynchronous",
"deviceTypes": [
"sensors"
],
"id": 1
}
}Schema
{
"properties": {
"data": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"name": {
"description": "Description of data collector type",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}Devices ¶
Device Collection ¶
Get list of devicesGET/api/v1/devices{?expand}{&type}
Example URI
GET /api/v1/devices?expand=firmware,image&type=Sensor
URI Parameters
- expand
string(optional) Example: firmware,imageExpand HREF properties to full objects (e.g. ?expand=firmware,image)
- type
string(optional) Example: SensorLimit result to devices with this device type
Response
200Body
{
"data": [
{
"addr": "aabbcc",
"upgrading": false,
"href": "https://localhost:3000/api/v1/devices/2",
"platform": "RF200",
"description": "test",
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
},
"firmware": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1"
},
"id": 2,
"deviceType": "Deck1"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"addr": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex: a18ca9, 04:3E:82).",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "Device MAC Address",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"platform": {
"description": "Hardware platform",
"type": "string"
},
"description": {
"description": "User defined name for the device",
"type": "string"
},
"image": {
"description": "Software on device",
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
},
"firmware": {
"description": "Firmware on device",
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"id": {
"description": "Unique identifier for this device",
"type": "integer"
},
"deviceType": {
"description": "Device type",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Create a devicePOST/api/v1/devices
Clients should use this endpoint to create a single new Device resource. If you need to create
a lot of new devices in a bulk operation, please refer to the “Device Batches” section.
Example URI
POST /api/v1/devices
Request
Body
{
"platform": "RF200",
"description": "Device1",
"addr": "ccddee",
"deviceType": "Deck1"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Add device",
"description": "A device",
"properties": {
"platform": {
"description": "The device platform (ex: RF200)",
"type": "string"
},
"addr": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex:\"a18ca9\", \"04:3E:82\").",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "SNAP Mac Address",
"type": "string"
},
"description": {
"description": "Description of the device",
"type": "string"
},
"deviceType": {
"description": "The type of device. This must exist in the database already.",
"type": "string"
}
},
"required": [
"addr",
"description",
"platform",
"deviceType"
],
"type": "object"
}Response
201Headers
Location: https://localhost:3000/api/v1/devices/6
Content-Type: application/jsonBody
{
"data": {
"addr": "ccddee",
"upgrading": false,
"href": "https://localhost:3000/api/v1/devices/6",
"platform": "RF200",
"description": "Device1",
"image": {
"href": "Unknown"
},
"firmware": {
"href": "Unknown"
},
"id": 6,
"deviceType": "Deck1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"addr": {
"description": "Address of device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"platform": {
"description": "Type of platform",
"type": "string"
},
"description": {
"description": "Description of device",
"type": "string"
},
"id": {
"description": "Unique identifier for device",
"type": "integer"
},
"deviceType": {
"description": "Type of device",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Can’t create this device because required device properties are missing.
Body
{
"error": {
"message": "The following properties are required: addr, description, platform, deviceType"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
404Couldn’t find a device type with the specified deviceType description.
Body
{
"error": {
"message": "Device type could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
409Some other device with this MAC address already exists.
Body
{
"error": {
"message": "A device with this address already exists"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Device ¶
Get a single deviceGET/api/v1/devices/{deviceId}
Example URI
GET /api/v1/devices/2
URI Parameters
- deviceId
integer(required) Example: 2Unique identifier for a device
Response
200Body
{
"data": {
"addr": "aabbcc",
"upgrading": false,
"href": "https://localhost:3000/api/v1/devices/2",
"platform": "RF200",
"description": "test",
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
},
"firmware": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1"
},
"id": 2,
"deviceType": "Deck1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"addr": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex: a18ca9, 04:3E:82).",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "Device MAC Address",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"platform": {
"description": "Hardware platform",
"type": "string"
},
"description": {
"description": "User defined name for the device",
"type": "string"
},
"image": {
"description": "Software on device",
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
},
"firmware": {
"description": "Firmware on device",
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"id": {
"description": "Unique identifier for this device",
"type": "integer"
},
"deviceType": {
"description": "Device type",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
404No device found for this identifier.
Body
{
"error": {
"message": "Device could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Update DevicePUT/api/v1/devices/{deviceId}
Example URI
PUT /api/v1/devices/2
URI Parameters
- deviceId
integer(required) Example: 2Unique identifier for a device
Request
Body
{
"platform": "RF200",
"description": "Device1",
"addr": "ccddee",
"deviceType": "Deck1"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Update device",
"description": "A device",
"properties": {
"platform": {
"description": "The device platform (ex: RF200)",
"type": "string"
},
"addr": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex:\"a18ca9\", \"04:3E:82\").",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "SNAP Mac Address",
"type": "string"
},
"description": {
"description": "Description of the device",
"type": "string"
},
"deviceType": {
"description": "The type of device. This must exist in the database already.",
"type": "string"
}
},
"type": "object"
}Response
200Headers
Content-Type: application/jsonBody
{
"data": {
"addr": "ccddee",
"upgrading": false,
"href": "https://localhost:3000/api/v1/devices/6",
"platform": "RF200",
"description": "Device1",
"image": {
"href": "Unknown"
},
"firmware": {
"href": "Unknown"
},
"id": 6,
"deviceType": "Deck1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"addr": {
"description": "Address of device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"platform": {
"description": "Type of platform",
"type": "string"
},
"description": {
"description": "Description of device",
"type": "string"
},
"image": {
"description": "Image of device",
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
},
"firmware": {
"description": "Firmware of device",
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"id": {
"description": "Unique identifier for device",
"type": "integer"
},
"deviceType": {
"description": "Type of device",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Can’t update this device because required device properties are missing.
Body
{
"error": {
"message": "The following properties are required: addr, description, platform, deviceType"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
404No device found for this identifier, or, couldn’t find a device type with the specified deviceType description.
Body
{
"error": {
"message": "Device could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
409Can’t update this device’s address to the specified address, because that address is assigned to some other device in the system.
Body
{
"error": {
"message": "A device with this address already exists"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Delete DeviceDELETE/api/v1/devices/{deviceId}
Example URI
DELETE /api/v1/devices/2
URI Parameters
- deviceId
integer(required) Example: 2Unique identifier for a device
Response
204The device was successfully deleted
Response
404No device found for this identifier.
Body
{
"error": {
"message": "Device could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Device Batches ¶
Batch Device Operations ¶
Create a Batch of DevicesPOST/api/v1/devices/batches
Use this endpoint to efficiently create a large number of Device resources.
Example URI
POST /api/v1/devices/batches
Request
Body
{
"devices": [
{
"platform": "RF200",
"addr": "60866a",
"description": "Device1",
"deviceType": "Deck1"
},
{
"platform": "RF200",
"addr": "608477",
"description": "Device2",
"deviceType": "Deck1"
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Add batch of devices",
"description": "Batch of devices",
"properties": {
"devices": {
"items": {
"required": [
"addr",
"description",
"platform",
"deviceType"
],
"properties": {
"platform": {
"minLength": 1,
"description": "The device platform (ex: RF200)",
"type": "string"
},
"description": {
"minLength": 1,
"description": "Description of the device",
"type": "string"
},
"addr": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex:\"a18ca9\", \"04:3E:82\").",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "SNAP Mac Address",
"type": "string"
},
"deviceType": {
"minLength": 1,
"description": "The type of device. This must exist in the database already.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"required": [
"devices"
],
"type": "object"
}Response
201Headers
Location: https://localhost:3000/api/v1/devices/batches/b38baa5f-ce28-41a3-9bdd-4a14934e826c
Content-Type: application/jsonBody
{
"data": {
"href": "https://localhost:3000/api/v1/devices/batches/b38baa5f-ce28-41a3-9bdd-4a14934e826c",
"devices": [
{
"addr": "60866a",
"upgrading": false,
"href": "https://localhost:3000/api/v1/devices/6",
"platform": "RF200",
"description": "Device1",
"image": {
"href": "Unknown"
},
"firmware": {
"href": "Unknown"
},
"id": 6,
"deviceType": "Deck1"
},
{
"addr": "608477",
"upgrading": false,
"href": "https://localhost:3000/api/v1/devices/7",
"platform": "RF200",
"description": "Device2",
"image": {
"href": "Unknown"
},
"firmware": {
"href": "Unknown"
},
"id": 7,
"deviceType": "Deck1"
}
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this batch of devices",
"type": "string"
},
"devices": {
"items": {
"properties": {
"addr": {
"description": "Address of device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"platform": {
"description": "Type of platform",
"type": "string"
},
"description": {
"description": "Description of device",
"type": "string"
},
"image": {
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
},
"firmware": {
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"id": {
"description": "Unique identifier for device",
"type": "integer"
},
"deviceType": {
"description": "Type of device",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Can’t create one or more devices because required device properties are missing.
Body
{
"error": {
"message": "The following properties are required: addr, description, platform, deviceType"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
404Couldn’t find a device type with the specified deviceType description.
Body
{
"error": {
"message": "Device type could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
409Some other device with this MAC address already exists.
Body
{
"error": {
"message": "A device with this address already exists"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Device Types ¶
Device Types Collection ¶
Handles requests for the /deviceTypes resource path.
Get list of device typesGET/api/v1/deviceTypes
Example URI
GET /api/v1/deviceTypes
Response
200Headers
Content-Type: application/jsonBody
{
"data": [
{
"href": "https://localhost:3000/api/v1/deviceTypes/",
"id": 1,
"description": "Some Device Type"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this device type resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"description": {
"description": "Name of device type",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Create device typePOST/api/v1/deviceTypes
Example URI
POST /api/v1/deviceTypes
Request
Body
{
"description": "Some Device Type"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Add device type",
"description": "A device type",
"properties": {
"description": {
"minLength": 1,
"description": "A unique device type",
"type": "string"
}
},
"required": [
"description"
],
"type": "object"
}Response
201Headers
Location: https://localhost:3000/api/v1/deviceTypes/1
Content-Type: application/jsonBody
{
"data": {
"href": "https://localhost:3000/api/v1/deviceTypes/1",
"id": 1,
"description": "Some Device Type"
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this device type resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"description": {
"description": "Name of device type",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
409A device type with this description already exists.
Body
{
"error": {
"message": "A device type with this description already exists"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Device Type ¶
Handles requests for the /deviceTypes/{deviceTypeId} resource path.
Get a single device typeGET/api/v1/deviceTypes/{deviceTypeId}
Example URI
GET /api/v1/deviceTypes/1
URI Parameters
- deviceTypeId
integer(required) Example: 1Unique identifier for a device type
Response
200Body
{
"data": [
{
"href": "https://localhost:3000/api/v1/deviceTypes/1",
"id": 1,
"description": "Some Device Type"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this device type resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"description": {
"description": "Name of device type",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Update device typePUT/api/v1/deviceTypes/{deviceTypeId}
Example URI
PUT /api/v1/deviceTypes/1
URI Parameters
- deviceTypeId
integer(required) Example: 1Unique identifier for a device type
Request
Body
{
"description": "Some Device Type"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Update device type",
"description": "A device type",
"properties": {
"description": {
"minLength": 1,
"description": "Type of device",
"type": "string"
}
},
"required": [
"description"
],
"type": "object"
}Response
200Headers
Content-Type: application/jsonBody
{
"data": {
"href": "https://localhost:3000/api/v1/deviceTypes/1",
"id": 1,
"description": "Some Device Type"
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this device type resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"description": {
"description": "Name of device type",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
404No device type found for this identifier.
Body
{
"error": {
"message": "Device type could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
409Some other device type with this description already exists.
Body
{
"error": {
"message": "A device type with this description already exists"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Delete device typeDELETE/api/v1/deviceTypes/{deviceTypeId}
Example URI
DELETE /api/v1/deviceTypes/1
URI Parameters
- deviceTypeId
integer(required) Example: 1Unique identifier for a device type
Response
204The device type was successfully deleted.
Response
404No device type found for this identifier.
Body
{
"error": {
"message": "Device type could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Firmware ¶
Firmware Collection ¶
The list of available firmware is determined by inspecting the SNAP firmware packages installed on your gateway; it does not necessarily correspond to all of the firmware currently available from Synapse Wireless.
Retrieve list of available firmwareGET/api/v1/firmware
Example URI
GET /api/v1/firmware
Response
200Returns an array of firmware resources. Note that if no SNAP firmware is available, this will return an empty array.
Headers
Content-Type: application/jsonBody
{
"data": [
{
"href": "https://localhost:3000/api/v1/firmware/2.6.9",
"version": "2.6.9"
},
{
"href": "https://localhost:3000/api/v1/firmware/2.7.1",
"version": "2.7.1"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
},
"version": {
"description": "Firmware version number",
"type": "string"
}
},
"description": "A SNAP firmware release",
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Firmware ¶
Retrieve specific firmware resourceGET/api/v1/firmware/{firmwareVersion}
Example URI
GET /api/v1/firmware/2.7.1
URI Parameters
- firmwareVersion
string(required) Example: 2.7.1Unique identifier for a firmware version
Response
200Returns the firmware resource corresponding to the specified version number.
Body
{
"data": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1",
"version": "2.7.1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
},
"version": {
"description": "Firmware version number",
"type": "string"
}
},
"description": "A SNAP firmware release",
"type": "object"
}
},
"type": "object"
}Response
404There is no available firmware corresponding to this firmware version number.
Body
{
"error": {
"message": "Firmware could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}License ¶
License ¶
Handles requests for the /license resource path.
Apply a SNAP Thing Services LicensePUT/api/v1/license
The license needs to be Base64-encoded before it can be uploaded to the SNAP Thing Services.
Please contact Synapse Customer Service to receive a license. A license gives you access to:
-
Bulk upgrades
-
Data collection with no node limit
-
Topology with no node limit
Example URI
PUT /api/v1/license
Response
200SNAP Thing Services License successfully applied
Delete the licenseDELETE/api/v1/license
Example URI
DELETE /api/v1/license
Response
204The license was successfully deleted
License Capabilities ¶
Handles requests for the /licenseCapabilities resource path.
Get license capabilitiesGET/api/v1/licenseCapabilities
Example URI
GET /api/v1/licenseCapabilities
Response
200Headers
Content-Type: application/jsonBody
{
"data": {
"dataCollector": true,
"types": [
"manage",
"deploy"
],
"siteDirector": true,
"customer": "John Smith",
"expiration": "2020-02-05",
"siteDoctor": true
}
}Schema
{
"properties": {
"data": {
"properties": {
"dataCollector": {
"description": "True if the Data Collector is licensed",
"type": "boolean"
},
"types": {
"items": {
"description": "License types",
"type": "string"
},
"type": "array"
},
"siteDirector": {
"description": "True if the Site Director is licensed",
"type": "boolean"
},
"customer": {
"description": "The licensed customer",
"type": "string"
},
"expiration": {
"description": "The date the license expires",
"type": "string"
},
"siteDoctor": {
"description": "True if the Site Doctor is licensed",
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
}SPY Images ¶
SPY Image Collection ¶
Get all SPY imagesGET/api/v1/images
Example URI
GET /api/v1/images
Response
200Returns an array of SPY file images previously uploaded to the service. If no SPY images have been uploaded, the response contains an empty array.
Body
{
"data": [
{
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"crc": "0xda95",
"size": 3489,
"name": "McastCounter",
"id": "6f992502-33f0-47d4-a01e-973593e1915d"
},
{
"href": "https://localhost:3000/api/v1/images/f97fdf18-fede-4d58-96d4-eb3f36b4b872",
"crc": "0x16f1",
"size": 690,
"name": "blink",
"id": "f97fdf18-fede-4d58-96d4-eb3f36b4b872"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this SPY image resource",
"type": "string"
},
"crc": {
"description": "Checksum of SPY image content",
"type": "string"
},
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
},
"name": {
"description": "The script name compiled into the SPY image",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Create a new SPY imagePOST/api/v1/images
You must create a SPY image resource in the service before it can be uploaded to a SNAP device.
To create a SPY image resource, obtain the Base64-encoded representation of the SPY image data
and pass it in as the content property’s value for this request.
Example URI
POST /api/v1/images
Request
Body
{
"content": "<Base64-encoded SPY file contents>"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Upload SPY image",
"description": "A SPY file image",
"properties": {
"content": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "Base64-encoded SPY image contents",
"type": "string"
}
},
"required": [
"content"
],
"type": "object"
}Response
201The SPY image resource was successfully created.
Headers
Location: https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915dBody
{
"data": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"crc": "0xda95",
"size": 3489,
"name": "McastCounter",
"id": "6f992502-33f0-47d4-a01e-973593e1915d"
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this SPY image resource",
"type": "string"
},
"crc": {
"description": "Checksum of SPY image content",
"type": "string"
},
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"name": {
"description": "The script name compiled into the SPY image",
"type": "string"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Delete all SPY imagesDELETE/api/v1/images
Example URI
DELETE /api/v1/images
Response
204All of the SPY image resources were successfully deleted.
SPY Image ¶
Get a single SPY imageGET/api/v1/images/{imageId}
Example URI
GET /api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d
URI Parameters
- imageId
string(required) Example: 6f992502-33f0-47d4-a01e-973593e1915dUnique identifier for a SPY image
Response
200Body
{
"data": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"crc": "0xda95",
"size": 3489,
"name": "McastCounter",
"id": "6f992502-33f0-47d4-a01e-973593e1915d"
}
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this SPY image resource",
"type": "string"
},
"crc": {
"description": "Checksum of SPY image content",
"type": "string"
},
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
},
"name": {
"description": "The script name compiled into the SPY image",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Response
404No SPY image found for this identifier.
Body
{
"error": {
"message": "Image could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Delete a SPY imageDELETE/api/v1/images/{imageId}
Example URI
DELETE /api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d
URI Parameters
- imageId
string(required) Example: 6f992502-33f0-47d4-a01e-973593e1915dUnique identifier for a SPY image
Response
204The SPY image resource was successfully deleted
Response
404No SPY image found for this identifier.
Body
{
"error": {
"message": "Image could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Synapse RF Module Types ¶
Synapse RF Module Type Collection ¶
Get Module TypesGET/api/v1/moduleTypes
Example URI
GET /api/v1/moduleTypes
Response
200An array of Synapse RF Module Types
Body
{
"data": [
{
"href": "https://localhost:3000/api/v1/moduleTypes/RF200PF1",
"partName": "RF200PF1"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this Synapse RF Module Type",
"type": "string"
},
"partName": {
"description": "Synapse RF Module Type Part Name",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Network Configuration ¶
Network Configurations Collection ¶
Get a List of All Network ConfigurationsGET/api/v1/networkConfigurations
Example URI
GET /api/v1/networkConfigurations
Response
200Returns an array of previously created network configuration resources.
Body
{
"data": [
{
"href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
"deviceGroupConfigurations": [
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
}
},
"devices": [
"03cd71",
"04ab44"
]
},
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
}
},
"devices": [
"00a400",
"040128"
]
}
],
"id": "7e968754-78f0-09f8-b57b-968745b2789e"
},
{
"href": "https://localhost:3000/api/v1/networkConfigurations/c5fe2546-78f0-09f8-b57b-968745b2789e",
"deviceGroupConfigurations": [
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/4d271412-33f0-47d4-a01e-973593e1915d"
}
},
"devices": [
"082614",
"7531df"
]
},
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/9e524135-3a66-49c0-9126-98c901cd6ee4"
}
},
"devices": [
"04abaf",
"604def"
]
}
],
"id": "c5fe2546-78f0-09f8-b57b-968745b2789e"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this network configuration resource",
"type": "string"
},
"deviceGroupConfigurations": {
"items": {
"properties": {
"configuration": {
"properties": {
"firmware": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SNAP firmware release",
"type": "object"
},
"image": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SPY image",
"type": "object"
}
},
"description": "A configuration that can be applied to one or more devices",
"type": "object"
},
"devices": {
"items": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex: 'a18ca9', '04:3E:82').",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "SNAP Mac address",
"type": "string"
},
"uniqueItems": true,
"description": "A group of devices",
"type": "array"
}
},
"description": "Associates a configuration with a group of devices",
"type": "object"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this network configuration resource",
"type": "string"
}
},
"description": "A network configuration resource",
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Create a Network ConfigurationPOST/api/v1/networkConfigurations
Describe a desired network configuration in terms of some number of device group-specific configurations.
Example URI
POST /api/v1/networkConfigurations
Request
Body
{
"deviceGroupConfigurations": [
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
}
},
"devices": [
"03cd71",
"04ab44"
]
},
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
}
},
"devices": [
"00a400",
"040128"
]
}
]
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Add network configuration",
"description": "A network configuration resource",
"properties": {
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"properties": {
"configuration": {
"properties": {
"firmware": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SNAP firmware release",
"type": "object"
},
"image": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SPY image",
"type": "object"
}
},
"description": "A configuration that can be applied to one or more devices",
"type": "object"
},
"devices": {
"items": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex:\"a18ca9\", \"04:3E:82\").",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "SNAP Mac address",
"type": "string"
},
"uniqueItems": true,
"description": "A group of devices",
"type": "array"
}
},
"description": "Associates a configuration with a group of devices",
"type": "object"
},
"type": "array"
}
},
"required": [
"deviceGroupConfigurations"
],
"type": "object"
}Response
201The network configuration resource was successfully created.
Headers
Location: https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789eBody
{
"data": {
"href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
"deviceGroupConfigurations": [
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
}
},
"devices": [
"03cd71",
"04ab44"
]
},
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
}
},
"devices": [
"00a400",
"040128"
]
}
],
"id": "7e968754-78f0-09f8-b57b-968745b2789e"
}
}Schema
{
"properties": {
"data": {
"required": [
"deviceGroupConfigurations"
],
"properties": {
"href": {
"description": "URI for this network configuration resource",
"type": "string"
},
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"properties": {
"configuration": {
"properties": {
"firmware": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SNAP firmware release",
"type": "object"
},
"image": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SPY image",
"type": "object"
}
},
"description": "A configuration that can be applied to one or more devices",
"type": "object"
},
"devices": {
"items": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex: 'a18ca9', '04:3E:82').",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "SNAP Mac address",
"type": "string"
},
"uniqueItems": true,
"description": "A group of devices",
"type": "array"
}
},
"description": "Associates a configuration with a group of devices",
"type": "object"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this network configuration resource",
"type": "string"
}
},
"description": "A network configuration resource",
"type": "object"
}
},
"type": "object"
}Network Configuration ¶
Get a Network ConfigurationGET/api/v1/networkConfigurations/{networkConfigurationId}
Example URI
GET /api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e
URI Parameters
- networkConfigurationId
string(required) Example: 7e968754-78f0-09f8-b57b-968745b2789eUnique identifier for a network configuration resource
Response
200Returns the network configuration resource for this identifier.
Body
{
"data": {
"href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
"deviceGroupConfigurations": [
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
}
},
"devices": [
"03cd71",
"04ab44"
]
},
{
"configuration": {
"image": {
"href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
}
},
"devices": [
"00a400",
"040128"
]
}
],
"id": "7e968754-78f0-09f8-b57b-968745b2789e"
}
}Schema
{
"properties": {
"data": {
"required": [
"deviceGroupConfigurations"
],
"properties": {
"href": {
"description": "URI for this network configuration resource",
"type": "string"
},
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"properties": {
"configuration": {
"properties": {
"firmware": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SNAP firmware release",
"type": "object"
},
"image": {
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"description": "A SPY image",
"type": "object"
}
},
"description": "A configuration that can be applied to one or more devices",
"type": "object"
},
"devices": {
"items": {
"pattern_description": "A valid SNAP Address must be a hex value of at least 6 digits with optional period or colon delimiters (ex: 'a18ca9', '04:3E:82').",
"pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
"description": "SNAP Mac address",
"type": "string"
},
"uniqueItems": true,
"description": "A group of devices",
"type": "array"
}
},
"description": "Associates a configuration with a group of devices",
"type": "object"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this network configuration resource",
"type": "string"
}
},
"description": "A network configuration resource",
"type": "object"
}
},
"type": "object"
}Response
404No network configuration resource found for this identifier.
Body
{
"error": {
"message": "Network configuration resource could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Network Configuration Updates ¶
Network Configuration Updates Collection ¶
Initiate a Network Configuration UpdatePOST/api/v1/networkConfigurationUpdates
A POST to this endpoint initiates a network configuration update, using the specified network configuration as the “recipe”. This is an asynchronous process that may take awhile to complete, so it immediately returns a 202 status (“Accepted”) and the location of a task resource that indicates the current status of this long-running update task.
Once a network configuration update is complete, the affected devices will be updated with their new firmware or script versions (assuming those updates were successful).
Example URI
POST /api/v1/networkConfigurationUpdates
Request
Body
{
"href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Apply a network configuration update",
"description": "A network configuration location",
"properties": {
"href": {
"description": "The location of a network configuration",
"type": "string"
}
},
"required": [
"href"
],
"type": "object"
}Response
202Headers
Location: https://localhost:3000/api/v1/tasks/8ba8d8bd-edeb-4960-bb05-87c75697bf6dResponse
400A network configuration update will not start if any number of errors are detected in the network configuration description (e.g. if the network configuration refers to unrecognized device MAC addresses). The message property of the error response should provide more details.
Body
{
"error": {
"message": "Unable to update network configuration: No devices found with address 608477"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
403A network configuration update will not start if the network configuration descriptionidentifies multiple devices but the user’s license restricts them to upgrading only onedevice at a time.
Body
{
"error": {
"message": "Your license only permits upgrading one device at a time. Please contact your sales representative to discuss upgrading your license to support upgrading multiple device at the same time."
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
404If the HREF in the message body refers to a non-existent network configuration, the response is 404 (Not Found).
Body
{
"error": {
"message": "Network configuration could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Network Configuration Updates ¶
Get results of a network configuration updateGET/api/v1/networkConfigurationUpdates/{networkConfigurationUpdateId}
Assuming the associated task of updating the network configuration is complete, this endpoint returns the results of that task. The results are group into firmware update results and image update results, on a device-by-device basis. If the attempted update of firmware or image for a device failed, the result value will be “failure”. If the update was successful, or if no update was attempted, the result value will be “success”.
Example URI
GET /api/v1/networkConfigurationUpdates/7e968754-78f0-09f8-b57b-968745b2789e
URI Parameters
- networkConfigurationUpdateId
string(required) Example: 7e968754-78f0-09f8-b57b-968745b2789eUnique identifier for a network configuration update result
Response
200Body
{
"data": {
"href": "https://localhost:3000/api/v1/networkConfigurationUpdates/9496aed3-1614-4207-8883-2c807958d940",
"image_results": [
{
"address": "60866a",
"result": "success"
},
{
"address": "608477",
"result": "success"
}
],
"firmware_results": [
{
"address": "60866a",
"result": "failure"
},
{
"address": "608477",
"result": "success"
}
],
"id": "9496aed3-1614-4207-8883-2c807958d940"
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this network configuration update results resource",
"type": "string"
},
"image_results": {
"items": {
"properties": {
"address": {
"description": "MAC address for the device described in this result",
"type": "string"
},
"result": {
"description": "Outcome of the attempted update, either success or failure",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"firmware_results": {
"items": {
"properties": {
"address": {
"description": "MAC address for the device described in this result",
"type": "string"
},
"result": {
"description": "Outcome of the attempted update, either success or failure",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this results set",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
404No such results
Body
{
"error": {
"message": "Network configuration update results could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Sockets ¶
SockJS Endpoint ¶
Connect SockJSGET/ws
See http://sockjs.org for details on making a connection.
Example URI
GET /ws
Response
200Body
"Established SockJS Connection"Tasks ¶
Task ¶
Get task statusGET/api/v1/tasks/{taskId}
A task resource is primarily useful as a handle for a long-running process,
such as updating the firmware on a group of devices, or computing the topology
for a SNAP mesh network.
If the response to a GET request for a task returns HTTP status 200 (OK),
the client can assume that this task is still in progress.
If the response to a GET request is HTTP status 303 (See Other),
the Location header of the response indicates the URI for the results of this
task. (Note that some HTTP clients will automatically redirect the client to this
location).
Example URI
GET /api/v1/tasks/7e968754-78f0-09f8-b57b-968745b2789e
URI Parameters
- taskId
string(required) Example: 7e968754-78f0-09f8-b57b-968745b2789eUnique identifier for a task
Response
200This long-running task (e.g. a network configuration update, or topology generation) is still in progress.
Body
{
"data": {
"href": "https://localhost:3000/api/v1/tasks/8ba8d8bd-edeb-4960-bb05-87c75697bf6d",
"id": "8ba8d8bd-edeb-4960-bb05-87c75697bf6d"
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI of this task resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this task",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
303This task is complete, and the Location header indicates where to find the results of this task.
Headers
Location: https://localhost:3000/api/v1/networkConfigurationUpdates/9496aed3-1614-4207-8883-2c807958d940Response
404No task found for this identifier.
Body
{
"error": {
"message": "Task could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}TCP Access ¶
TCP Access ¶
Handles requests to enable or disable SNAPconnect TCP access.
Get TCP access stateGET/api/v1/tcpAccess
Example URI
GET /api/v1/tcpAccess
Response
200Body
{
"data": {
"tcpAccessEnabled": true
}
}Schema
{
"properties": {
"data": {
"properties": {
"tcpAccessEnabled": {
"description": "Indicates whether TCP access is enabled",
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
}Enable TCP accessPOST/api/v1/tcpAccess
Example URI
POST /api/v1/tcpAccess
Request
Body
{
"password": "Synapse$0123",
"username": "snap"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Add device type",
"description": "A device type",
"properties": {
"password": {
"minLength": 1,
"description": "Password for the TCP connection",
"type": "string"
},
"username": {
"minLength": 1,
"description": "Username for the TCP connection",
"type": "string"
}
},
"required": [
"username",
"password"
],
"type": "object"
}Response
201Successfully opened TCP connection
Response
409TCP access has already been enabled.
Body
{
"error": {
"message": "TCP access has already been enabled"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Disable TCP accessDELETE/api/v1/tcpAccess
Disabling TCP access will prevent new connections but not close existing ones.
Example URI
DELETE /api/v1/tcpAccess
Response
204TCP successfully disabled.
Topologies ¶
SNAP Network Topology Collection ¶
Get all topologiesGET/api/v1/topologies
Returns an array of the previously generated topologies.
Topology results are limited to 5 nodes when using a trial license. Please contact your sales representative to discuss upgrading your license to support retrieving full topology results.
Example URI
GET /api/v1/topologies
Response
200Body
{
"data": [
{
"href": "https://localhost:3000/api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"createdAt": "2016-07-27T13:57:43.361554Z",
"gateways": [
"608509"
],
"links": [
{
"start": "608509",
"linkQuality": 71,
"end": "5ecad4"
},
{
"start": "5ecad4",
"linkQuality": 68,
"end": "608509"
}
]
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"href": {
"description": "URI for this topology resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this topology resource",
"type": "string"
},
"createdAt": {
"description": "Topology creation date (ISO8601 format)",
"type": "string"
},
"gateways": {
"items": {
"description": "Gateway MAC address",
"type": "string"
},
"type": "array"
},
"links": {
"items": {
"properties": {
"start": {
"description": "Start address for this link",
"type": "string"
},
"linkQuality": {
"description": "Link quality for this link (-dBm)",
"type": "integer"
},
"end": {
"description": "End address for this link",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Initiate Generation of the SNAP Network TopologyPOST/api/v1/topologies
A POST to this endpoint initiates generation of the SNAP network topology. This is an asynchronous process that may take awhile to complete, depending on the number of nodes in your network, so it immediately returns a 202 status (“Accepted”) and the location of a task resource that indicates the current status of this long-running task. Clients can poll this task to determine when it has completed, and where to find the topology results.
Example URI
POST /api/v1/topologies
Response
202Headers
Location: https://localhost:3000/api/v1/tasks/83f4e242-e89d-407b-95e5-a5a603427217Delete all topologiesDELETE/api/v1/topologies
Delete from storage all previously generated topologies.
Example URI
DELETE /api/v1/topologies
Response
204SNAP Network Topology ¶
Get topologyGET/api/v1/topologies/{topologyId}
Returns information about this previously generated topology. The mesh network topology is represented in terms of an array of links, where each link is described by its starting and ending SNAP node address as well as the link quality (in -dBm) between those two nodes.
Note that because the link quality is reported in units of -dBm, small values of link quality (closer to zero) indicate high link quality, while larger values (e.g. greater than 80) indicate low link quality.
Topology results are limited to 5 nodes when using a trial license. Please contact your sales representative to discuss upgrading your license to support retrieving full topology results.
Example URI
GET /api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c
URI Parameters
- topologyId
string(required) Example: 525a2d06-bfa4-4ad5-b3a1-c614bc367d9cUnique identifier for a topology, or
latestto refer to the topology with the most recentcreatedAttimestamp
Response
200Body
{
"data": {
"href": "https://localhost:3000/api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"createdAt": "2016-07-27T13:57:43.361554Z",
"gateways": [
"608509"
],
"links": [
{
"start": "608509",
"linkQuality": 71,
"end": "5ecad4"
},
{
"start": "5ecad4",
"linkQuality": 68,
"end": "608509"
}
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this topology resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this topology resource",
"type": "string"
},
"createdAt": {
"description": "Topology creation date (ISO8601 format)",
"type": "string"
},
"gateways": {
"items": {
"description": "Gateway MAC address",
"type": "string"
},
"type": "array"
},
"links": {
"items": {
"properties": {
"start": {
"description": "Start address for this link",
"type": "string"
},
"linkQuality": {
"description": "Link quality for this link (-dBm)",
"type": "integer"
},
"end": {
"description": "End address for this link",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}Response
404No device found for this identifier.
Body
{
"error": {
"message": "Topology could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Delete topologyDELETE/api/v1/topologies/{topologyId}
Delete the stored information about this previously generated topology.
Example URI
DELETE /api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c
URI Parameters
- topologyId
string(required) Example: 525a2d06-bfa4-4ad5-b3a1-c614bc367d9cUnique identifier for a topology, or
latestto refer to the topology with the most recentcreatedAttimestamp
Response
204Response
404No device found for this identifier.
Body
{
"error": {
"message": "Topology could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}