SNAP Thing Services API
SNAP Thing Services API Version 1.7.1
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 lowercase and uppercase letters, numbers, and symbols.
Example URI
POST /api/v1/changePassword
Request
Body
{
"new": "yourNewPassword1#",
"old": "yourOldPassword"
}Schema
{
"title": "Update device",
"properties": {
"new": {
"description": "New password",
"pattern_description": "Password must be at least 8 characters and include a combination of lowercase and uppercase letters, numbers, and symbols.",
"pattern": "^(?=.*[0-9])(?=.*[!@#$%^&*_\\-])(?=.*?[a-z])(?=.*?[A-Z])[a-zA-Z0-9!@#$%^&*_\\-]{8,}$",
"type": "string"
},
"old": {
"description": "Old password",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"old",
"new"
],
"description": "A device",
"type": "object"
}Response
200Successfully updated password.
Body
{
"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 lowercase and uppercase letters, numbers, and symbols."
}
}
}Schema
{
"properties": {
"error": {
"message": {
"type": "string"
},
"type": "object"
}
},
"type": "object"
}Actuation ¶
Actuation Config api handler to toggle actuation ¶
Used to get the actuation config statusGET/api/v1/actuation/config
Example URI
GET /api/v1/actuation/config
Response
200actuation enabled status
Body
{
"data": {
"isActuationEnabled": true
}
}Schema
{
"properties": {
"data": {
"properties": {
"isActuationEnabled": {
"description": "true or false",
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
}Used to toggle actuation requestPOST/api/v1/actuation/config
Example URI
POST /api/v1/actuation/config
Request
Body
{
"isActuationEnabled": false
}Schema
{
"title": "Toggle Actuation for devices",
"properties": {
"isActuationEnabled": {
"description": "True or False",
"type": "boolean"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"isActuationEnabled"
],
"description": "Toggle Actuation for devices",
"type": "object"
}Response
200actuation enabled status
Body
{
"data": {
"isActuationEnabled": true
}
}Schema
{
"properties": {
"data": {
"properties": {
"isActuationEnabled": {
"description": "true or false",
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
}Actuation api handler ¶
Get all actuation resultsGET/api/v1/actuation/requests
Example URI
GET /api/v1/actuation/requests
Response
200List all actuation results.
Body
{
"data": [
{
"parameters": [
256
],
"createdAt": "2017-01-12T08:50:21.506736",
"startedAt": "2017-01-12T08:50:21.726736",
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"function": "light_level",
"results": [
{
"result": "success",
"address": "098231"
},
{
"result": "failure",
"address": "09a1b4"
}
],
"finishedAt": "2017-01-12T08:50:21.846736",
"href": "https://localhost:3000/api/v1/actuation/requests/6f992502-33f0-47d4-a01e-973593e1915d",
"deviceTypes": [],
"devices": [
"098231",
"09a1b4"
]
},
{
"parameters": [],
"createdAt": "2017-01-10T08:50:21.506736",
"startedAt": "2017-01-10T08:50:21.726736",
"id": "7r592502-33f0-47d4-a01e-973593e1915d",
"function": "actuate_me",
"results": [
{
"result": "success",
"address": "098231"
}
],
"finishedAt": "2017-01-10T08:50:21.846736",
"href": "https://localhost:3000/api/v1/actuation/requests/7r592502-33f0-47d4-a01e-973593e1915d",
"deviceTypes": [
"devicetype1"
],
"devices": []
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"parameters": {
"items": {
"description": "List of parameters",
"anyOf": [
{
"type": [
"string",
"boolean",
"null",
"integer"
]
}
]
},
"type": "array"
},
"createdAt": {
"description": "Time at which actuation initiated",
"type": "string"
},
"startedAt": {
"description": "Time at which actuation started",
"type": "string"
},
"id": {
"description": "Unique identifier for this actuation",
"type": "string"
},
"function": {
"description": "Function Name",
"type": "string"
},
"results": {
"description": "Result of actuation request",
"type": "string"
},
"finishedAt": {
"description": "Time at which actuation finished",
"type": "string"
},
"href": {
"description": "URI for this actuation result",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "List of name of device type",
"type": "string"
},
"type": "array"
},
"devices": {
"items": {
"description": "List of device MAC addresses",
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Creates new actuation requestPOST/api/v1/actuation/requests
Example URI
POST /api/v1/actuation/requests
Request
Body
{
"parameters": [
"<stringval>",
1,
null,
true
],
"deviceTypes": [
"thesedevices",
"thosedevices"
],
"function": "actuate_me",
"devices": [
"0600a3",
"0833a4",
"0534fe"
]
}Schema
{
"title": "Actuate devices",
"properties": {
"parameters": {
"items": {
"anyOf": [
{
"type": [
"string",
"boolean",
"null",
"integer"
]
}
]
},
"type": "array"
},
"deviceTypes": {
"items": {
"description": "List of types of device. This must exist in the database already.",
"type": "string"
},
"type": "array"
},
"function": {
"pattern": "^[a-zA-Z]\\w*$",
"pattern_description": "Actuation functions must be valid public SNAPpy functions. (ex: 'data', 'actuate_2B')",
"description": "SNAPpy script function",
"type": "string"
},
"devices": {
"items": {
"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]$",
"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\").",
"description": "SNAP MAC address",
"type": "string"
},
"type": "array"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"function"
],
"description": "Actuate devices",
"type": "object"
}Response
202Headers
Location: https://localhost:3000/api/v1/tasks/83f4e242-e89d-407b-95e5-a5a603427217Response
400At least one device address required
Body
{
"error": {
"message": "At least one device address required"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Parameter string should be base64 encoded
Body
{
"error": {
"message": "Parameter string should be base64 encoded"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Combined size of function name and parameter list exceeds maximum packet size
Body
{
"error": {
"message": "Combined size of function name and parameter list exceeds maximum packet size"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Response
400If actuation is unlicensed, an actuation request which targets multiple devices will not be sent
Body
{
"error": {
"message": "Your license only permits actuation of one device at a time. Please contact your sales representative to discuss upgrading your license to support multiple simultaneous actuations."
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Actuation result handler ¶
Get a single actuation resultGET/api/v1/actuation/requests/{actuationId}
Example URI
GET /api/v1/actuation/requests/1
URI Parameters
- actuationId
integer(required) Example: 1Unique identifier for an actuation result
Response
200Get actuation result details.
Body
{
"data": {
"parameters": [],
"createdAt": "2017-01-10T08:50:21.506736",
"startedAt": "2017-01-10T08:50:21.726736",
"id": "e00667ce-78b5-4595-8288-3ff0e50ed147",
"function": "actuate_me",
"results": [
{
"result": "failure",
"address": "60866a"
},
{
"result": "success",
"address": "608477"
}
],
"finishedAt": "2017-01-10T08:50:21.846736",
"href": "https://localhost:3000/api/v1/actuation/requests/e00667ce-78b5-4595-8288-3ff0e50ed147",
"deviceTypes": [
"devicetype1"
],
"devices": []
}
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"parameters": {
"items": {
"description": "List of parameters",
"anyOf": [
{
"type": [
"string",
"boolean",
"null",
"integer"
]
}
]
},
"type": "array"
},
"createdAt": {
"description": "Time at which actuation initiated",
"type": "string"
},
"startedAt": {
"description": "Time at which actuation started",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"function": {
"description": "Name of the function",
"type": "string"
},
"results": {
"items": {
"result": {
"description": "Outcome of the attempted actuation, either success or failure",
"type": "string"
},
"address": {
"description": "MAC address for the device described in this result",
"type": "string"
}
},
"type": "array"
},
"finishedAt": {
"description": "Time at which actuation finished",
"type": "string"
},
"href": {
"description": "URI for this device type resource",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "List of device type descriptions",
"type": "string"
},
"type": "array"
},
"devices": {
"items": {
"description": "List of device MAC addresses",
"type": "string"
},
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Response
404No such result.
Body
{
"error": {
"message": "Actuation result could not be found"
}
}Schema
{
"properties": {
"error": {
"properties": {
"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
200Successfully backed up database
Body
"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
200Get current network settings details.
Body
{
"data": {
"actual_settings": {
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"networkId": "0x3ab3",
"channel": 10,
"encryptionType": "AES-128",
"rpcCrc": false,
"packetCrc": true
},
"bridge_addr": "012345",
"configured_settings": {
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"networkId": "0x3ab3",
"channel": 10,
"encryptionType": "AES-128",
"rpcCrc": false,
"packetCrc": true
}
}
}Schema
{
"properties": {
"data": {
"properties": {
"actual_settings": {
"description": "Actual bridge node network settings",
"properties": {
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check is enabled",
"type": "boolean"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation is enabled",
"type": "boolean"
}
},
"type": "object"
},
"bridge_addr": {
"description": "Device MAC address",
"type": "string"
},
"configured_settings": {
"description": "Configured network settings",
"properties": {
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check should be enabled",
"type": "boolean"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation should be enabled",
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Could not get network settings.
Body
{
"apiVersion": "v1",
"error": {
"code": 400,
"message": "Could not get network settings"
}
}Schema
{
"properties": {
"apiVersion": {
"type": "string"
},
"error": {
"properties": {
"code": {
"description": "HTTP response status",
"type": "integer"
},
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Update the current network settingsPUT/api/v1/network
Example URI
PUT /api/v1/network
Request
Body
{
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"networkId": "0x3ab3",
"channel": 10,
"encryptionType": "AES-128",
"rpcCrc": false,
"packetCrc": true
}Schema
{
"title": "Update network settings",
"properties": {
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check should be enabled",
"type": "boolean"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation should be enabled",
"type": "boolean"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"channel",
"networkId",
"rpcCrc",
"packetCrc",
"encryptionType",
"encryptionKey"
],
"description": "A group of network settings",
"type": "object"
}Response
200Successfully updated network settings.
Headers
Content-Type: application/jsonBody
{
"data": {
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"networkId": "0x3ab3",
"channel": 10,
"encryptionType": "AES-128",
"rpcCrc": false,
"packetCrc": true
}
}Schema
{
"properties": {
"data": {
"properties": {
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "The Base64 encoded encryption key",
"type": "string"
},
"networkId": {
"description": "The network identifier (ex: '0x1c2c')",
"type": "string"
},
"channel": {
"description": "The RF channel",
"type": "integer"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"rpcCrc": {
"description": "Indicates whether the RPC CRC packet integrity check is enabled",
"type": "boolean"
},
"packetCrc": {
"description": "Indicates whether packet-level CRC validation is enabled",
"type": "boolean"
}
},
"type": "object"
}
},
"type": "object"
}Response
400Could not update network settings.
Body
{
"apiVersion": "v1",
"error": {
"code": 400,
"message": "Could not update network settings"
}
}Schema
{
"properties": {
"apiVersion": {
"type": "string"
},
"error": {
"properties": {
"code": {
"description": "HTTP response status",
"type": "integer"
},
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Data Collector ¶
Data Collector Collection ¶
Get the list of data collectorsGET/api/v1/dc
Example URI
GET /api/v1/dc
Response
200List all data collectors.
Headers
Content-Type: application/jsonBody
{
"data": [
{
"href": "https://localhost:3000/api/v1/dc/dc1",
"id": 1,
"name": "dc1",
"data_collector_type": "asynchronous",
"initRpcName": "setReceiverAddress",
"deviceTypes": [
"sensors"
],
"dataRpcName": "acceptData"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}Create a data collectorPOST/api/v1/dc
Example URI
POST /api/v1/dc
Request
Body
{
"queryFunction": "data",
"dataCollectorType": "synchronous",
"deviceTypes": [
"sensors"
],
"pollInterval": 60,
"name": "dc1"
}Schema
{
"title": "Add data collector",
"properties": {
"initRpcName": {
"anyOf": [
{
"description": "Name of function implemented by SNAPpy script (required for async only)",
"pattern_description": "Init functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string"
},
{
"type": "null"
}
]
},
"queryFunction": {
"description": "Name of query function (required for sync only)",
"pattern_description": "Query functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string"
},
"name": {
"description": "Name of data collector",
"pattern_description": "Data collector names must be letters, numbers, underscores, periods, and dashes. (ex: 'dc1', 'Data_Collector.1-b')",
"pattern": "^[A-z0-9_.-]+$",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (required for sync only)",
"minimum": 5,
"maximum": 86400,
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (required for async only)",
"pattern_description": "Data functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"name",
"deviceTypes"
],
"description": "A data collector",
"type": "object"
}Response
201Successfully created data collector.
Body
{
"data": {
"initRpcName": "setReceiverAddress",
"id": 1,
"name": "dc1",
"dataCollectorType": "asynchronous",
"deviceTypes": [
"sensors"
],
"dataRpcName": "acceptData",
"href": "https://localhost:3000/api/v1/dc/dc1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this data collector resource",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
}
},
"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
204Successfully deleted data collector.
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
200Get data collector details.
Headers
Content-Type: application/jsonBody
{
"data": {
"href": "https://localhost:3000/api/v1/dc/dc1",
"queryFunction": "data",
"id": 1,
"name": "dc1",
"pollInterval": 60,
"dataCollectorType": "synchronous",
"deviceTypes": [
"sensors"
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
}
},
"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
{
"dataCollectorType": "asynchronous",
"deviceTypes": [
"sensors"
],
"initRpcName": "setReceiverAddress",
"name": "dc1",
"dataRpcName": "acceptData"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A data collector",
"title": "Update a data collector",
"properties": {
"initRpcName": {
"anyOf": [
{
"description": "Name of function implemented by SNAPpy script (required for async only)",
"pattern_description": "Init functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string"
},
{
"type": "null"
}
]
},
"queryFunction": {
"description": "Name of query function (required for sync only)",
"pattern_description": "Query functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string"
},
"name": {
"description": "Name of data collector",
"pattern_description": "Data collector names must be letters, numbers, underscores, periods, and dashes. (ex: 'dc1', 'Data_Collector.1-b')",
"pattern": "^[A-z0-9_.-]+$",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (required for sync only)",
"minimum": 5,
"maximum": 86400,
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (required for async only)",
"pattern_description": "Data functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string"
}
},
"type": "object"
}Response
200Successfully updated data collector.
Body
{
"data": {
"initRpcName": "setReceiverAddress",
"id": 1,
"name": "dc1",
"dataCollectorType": "asynchronous",
"deviceTypes": [
"sensors"
],
"dataRpcName": "acceptData",
"href": "https://localhost:3000/api/v1/dc/dc1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"id": {
"description": "Unique identifier for this data collector",
"type": "integer"
},
"name": {
"description": "Description of data collector type",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
}
},
"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
200List all devices.
Body
{
"data": [
{
"addr": "aabbcc",
"deviceType": "Deck1",
"href": "https://localhost:3000/api/v1/devices/2",
"id": 2,
"platform": "RF200",
"description": "test",
"upgrading": false,
"firmware": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1"
},
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
}
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"addr": {
"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]$",
"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).",
"description": "Device MAC address",
"type": "string"
},
"deviceType": {
"description": "Device type",
"type": "string"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this device",
"type": "integer"
},
"platform": {
"description": "Hardware platform",
"type": "string"
},
"description": {
"description": "User defined name for the device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"firmware": {
"description": "Firmware on device",
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"image": {
"description": "Software on device",
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
}
},
"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 <device_batches.html>_ section.
Example URI
POST /api/v1/devices
Request
Body
{
"addr": "ccddee",
"deviceType": "Deck1",
"description": "Device1",
"platform": "RF200"
}Schema
{
"title": "Add device",
"properties": {
"addr": {
"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]$",
"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\").",
"description": "SNAP MAC address",
"type": "string"
},
"deviceType": {
"description": "The type of device. This must exist in the database already.",
"type": "string"
},
"description": {
"description": "Description of the device",
"type": "string"
},
"platform": {
"description": "The device platform (ex: RF200)",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"addr",
"description",
"platform",
"deviceType"
],
"description": "A device",
"type": "object"
}Response
201Successfully created device.
Headers
Location: https://localhost:3000/api/v1/devices/6
Content-Type: application/jsonBody
{
"data": {
"addr": "ccddee",
"deviceType": "Deck1",
"href": "https://localhost:3000/api/v1/devices/6",
"id": 6,
"platform": "RF200",
"description": "Device1",
"upgrading": false,
"firmware": {
"href": "Unknown"
},
"image": {
"href": "Unknown"
}
}
}Schema
{
"properties": {
"data": {
"properties": {
"addr": {
"description": "Address of device",
"type": "string"
},
"deviceType": {
"description": "Type of device",
"type": "string"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"id": {
"description": "Unique identifier for device",
"type": "integer"
},
"platform": {
"description": "Type of platform",
"type": "string"
},
"description": {
"description": "Description of device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
}
},
"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
200Get device details.
Body
{
"data": {
"addr": "aabbcc",
"deviceType": "Deck1",
"href": "https://localhost:3000/api/v1/devices/2",
"id": 2,
"platform": "RF200",
"description": "test",
"upgrading": false,
"firmware": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1"
},
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
}
}
}Schema
{
"properties": {
"data": {
"properties": {
"addr": {
"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]$",
"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).",
"description": "Device MAC address",
"type": "string"
},
"deviceType": {
"description": "Device type",
"type": "string"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this device",
"type": "integer"
},
"platform": {
"description": "Hardware platform",
"type": "string"
},
"description": {
"description": "User defined name for the device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"firmware": {
"description": "Firmware on device",
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"image": {
"description": "Software on device",
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
}
},
"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
{
"addr": "ccddee",
"deviceType": "Deck1",
"description": "Device1",
"platform": "RF200"
}Schema
{
"type": "object",
"description": "A device",
"properties": {
"addr": {
"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]$",
"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\").",
"description": "SNAP MAC address",
"type": "string"
},
"deviceType": {
"description": "The type of device. This must exist in the database already.",
"type": "string"
},
"description": {
"description": "Description of the device",
"type": "string"
},
"platform": {
"description": "The device platform (ex: RF200)",
"type": "string"
}
},
"title": "Update device",
"$schema": "http://json-schema.org/draft-04/schema#"
}Response
200Successfully updated device.
Headers
Content-Type: application/jsonBody
{
"data": {
"addr": "ccddee",
"deviceType": "Deck1",
"href": "https://localhost:3000/api/v1/devices/6",
"id": 6,
"platform": "RF200",
"description": "Device1",
"upgrading": false,
"firmware": {
"href": "Unknown"
},
"image": {
"href": "Unknown"
}
}
}Schema
{
"properties": {
"data": {
"properties": {
"addr": {
"description": "Address of device",
"type": "string"
},
"deviceType": {
"description": "Type of device",
"type": "string"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"id": {
"description": "Unique identifier for device",
"type": "integer"
},
"platform": {
"description": "Type of platform",
"type": "string"
},
"description": {
"description": "Description of device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"firmware": {
"description": "Firmware of device",
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"image": {
"description": "Image of device",
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
}
},
"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
204Successfully deleted device.
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": [
{
"addr": "60866a",
"deviceType": "Deck1",
"description": "Device1",
"platform": "RF200"
},
{
"addr": "608477",
"deviceType": "Deck1",
"description": "Device2",
"platform": "RF200"
}
]
}Schema
{
"title": "Add batch of devices",
"properties": {
"devices": {
"items": {
"required": [
"addr",
"description",
"platform",
"deviceType"
],
"properties": {
"addr": {
"description": "SNAP MAC address",
"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]$",
"type": "string"
},
"deviceType": {
"description": "The type of device. This must exist in the database already.",
"minLength": 1,
"type": "string"
},
"description": {
"description": "Description of the device",
"minLength": 1,
"type": "string"
},
"platform": {
"description": "The device platform (ex: RF200)",
"minLength": 1,
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"devices"
],
"description": "Batch of devices",
"type": "object"
}Response
201Successfully created devices.
Headers
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",
"deviceType": "Deck1",
"href": "https://localhost:3000/api/v1/devices/6",
"id": 6,
"platform": "RF200",
"description": "Device1",
"upgrading": false,
"firmware": {
"href": "Unknown"
},
"image": {
"href": "Unknown"
}
},
{
"addr": "608477",
"deviceType": "Deck1",
"href": "https://localhost:3000/api/v1/devices/7",
"id": 7,
"platform": "RF200",
"description": "Device2",
"upgrading": false,
"firmware": {
"href": "Unknown"
},
"image": {
"href": "Unknown"
}
}
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this batch of devices",
"type": "string"
},
"devices": {
"items": {
"properties": {
"addr": {
"description": "Address of device",
"type": "string"
},
"deviceType": {
"description": "Type of device",
"type": "string"
},
"href": {
"description": "URI for this device resource",
"type": "string"
},
"id": {
"description": "Unique identifier for device",
"type": "integer"
},
"platform": {
"description": "Type of platform",
"type": "string"
},
"description": {
"description": "Description of device",
"type": "string"
},
"upgrading": {
"description": "Indicates whether device is upgrading",
"type": "boolean"
},
"firmware": {
"properties": {
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"type": "object"
},
"image": {
"properties": {
"href": {
"description": "URI for this image resource",
"type": "string"
}
},
"type": "object"
}
},
"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 ¶
Get list of device typesGET/api/v1/deviceTypes
Example URI
GET /api/v1/deviceTypes
Response
200List all device types.
Headers
Content-Type: application/jsonBody
{
"data": [
{
"description": "Some Device Type",
"id": 1,
"href": "https://localhost:3000/api/v1/deviceTypes/"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"description": {
"description": "Name of device type",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"href": {
"description": "URI for this device type resource",
"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
{
"title": "Add device type",
"properties": {
"description": {
"description": "A unique device type",
"minLength": 1,
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"description"
],
"description": "A device type",
"type": "object"
}Response
201Successfully created device type.
Headers
Location: https://localhost:3000/api/v1/deviceTypes/1
Content-Type: application/jsonBody
{
"data": {
"description": "Some Device Type",
"id": 1,
"href": "https://localhost:3000/api/v1/deviceTypes/1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"description": {
"description": "Name of device type",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"href": {
"description": "URI for this device type resource",
"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 ¶
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
200Get device type details.
Body
{
"data": [
{
"description": "Some Device Type",
"id": 1,
"href": "https://localhost:3000/api/v1/deviceTypes/1"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"description": {
"description": "Name of device type",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"href": {
"description": "URI for this device type resource",
"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
{
"title": "Update device type",
"properties": {
"description": {
"description": "Type of device",
"minLength": 1,
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"description"
],
"description": "A device type",
"type": "object"
}Response
200Successfully updated device type.
Headers
Content-Type: application/jsonBody
{
"data": {
"description": "Some Device Type",
"id": 1,
"href": "https://localhost:3000/api/v1/deviceTypes/1"
}
}Schema
{
"properties": {
"data": {
"properties": {
"description": {
"description": "Name of device type",
"type": "string"
},
"id": {
"description": "Unique identifier for this device type",
"type": "integer"
},
"href": {
"description": "URI for this device type resource",
"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
204Successfully deleted device type.
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
200List all firmware resources.Note that if no SNAP firmware is available, this will return an empty array.
Headers
Content-Type: application/jsonBody
{
"data": [
{
"version": "2.6.9",
"href": "https://localhost:3000/api/v1/firmware/2.6.9"
},
{
"version": "2.7.1",
"href": "https://localhost:3000/api/v1/firmware/2.7.1"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"description": "A SNAP firmware release",
"properties": {
"version": {
"description": "Firmware version number",
"type": "string"
},
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"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
200Get firmware resource details.
Body
{
"data": {
"version": "2.7.1",
"href": "https://localhost:3000/api/v1/firmware/2.7.1"
}
}Schema
{
"properties": {
"data": {
"description": "A SNAP firmware release",
"properties": {
"version": {
"description": "Firmware version number",
"type": "string"
},
"href": {
"description": "URI for this firmware resource",
"type": "string"
}
},
"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 ¶
Apply a LicensePUT/api/v1/license
The license needs to be Base64-encoded before it can be uploaded to 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, and topology generation with no node limit.
Example URI
PUT /api/v1/license
Response
200Successfully applied SNAP Thing Services License
Delete the licenseDELETE/api/v1/license
Example URI
DELETE /api/v1/license
Response
204The license was successfully deleted.
License Capabilities ¶
Get license capabilitiesGET/api/v1/licenseCapabilities
Example URI
GET /api/v1/licenseCapabilities
Response
200Get current license details.
Headers
Content-Type: application/jsonBody
{
"data": {
"siteDoctor": true,
"dataCollector": true,
"actuation": true,
"siteDirector": true,
"expiration": "2020-02-05",
"customer": "John Smith",
"types": [
"manage",
"deploy"
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"siteDoctor": {
"description": "True if the Site Doctor is licensed",
"type": "boolean"
},
"dataCollector": {
"description": "True if the Data Collector is licensed",
"type": "boolean"
},
"actuation": {
"description": "True if Actuation is licensed",
"type": "boolean"
},
"siteDirector": {
"description": "True if the Site Director is licensed",
"type": "boolean"
},
"expiration": {
"description": "The date the license expires",
"type": "string"
},
"customer": {
"description": "The licensed customer",
"type": "string"
},
"types": {
"items": {
"description": "License types",
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}Site Configuration ¶
Import Site Configuration ¶
Get site configurationGET/api/v1/siteConfig
Example URI
GET /api/v1/siteConfig
Response
200Returns an exported site configuration.
Body
{
"data": {
"dataCollectors": [
{
"dataCollectorType": "asynchronous",
"deviceTypes": [
"sensors"
],
"initRpcName": "setReceiverAddress",
"name": "dc1",
"dataRpcName": "acceptData"
},
{
"queryFunction": "data",
"dataCollectorType": "synchronous",
"deviceTypes": [
"lights"
],
"pollInterval": 60,
"name": "dc2"
}
],
"deviceTypes": [
{
"description": "a device type description"
},
{
"description": "another device type description"
}
],
"images": [
{
"size": 3489,
"file": "/d9CprNlBqsxQ8oJ+23SCfkIrXOaoUIaxHNoVK5xo3FLuS9uDXBRO1ommFU6wmMvssqK13qPGMFBe7gc/IaZY8c6fK0KnAgY/WPZWAsQGi1xDP+L7hoi8J0lts3BCJ1czjzCE9y4H176wcKqyezON3FW/0HvYJG9WpgR18eKFe6mW3ylE5QAltxIQG8jQBlXsOU82J7G8mdsds9prCbC8A2Vqiekmgza4Q7l6MnStBilePZxqhYipsWnifMiq4UsHatKcnfZd7ohnf49wQLMS8h1t3R/WYcYfJy7VSso8g6wJ8K5LRv1l3AH1qE9ohJERfc7C1aWAq/ApYIVTBxcFt6yuytjskB1QWoXoQ6l+9qmR//H8KiQbWcw6D/j5FBW61Py1ZHU45r66FSP1FeqjCv9dwGx5qkF9OSM0g9bsObdahldQ1nS1xdV+Zg/RkVSAeeMmrFqg3tTPLslRbckDW6kj/F/KZaiqrAjjK25REMjcEv9aRg8lBiwqvxLcAev6Kd3KKH27rlqH3WhbrYBe4AUFw7kNgjPQ3gIX8jf0HJOl3PZO32FuJksQfjvO7xW94sXC0BUbXrszZ+WDKMY4rmN2YGHflE9L+yChq/DpKSuG2eahqLb915osWahSDd2RQ27aQ3SDXwd8jKwAjpxKR0FWxp8yLDgoIUFJwWJBjyun+4f+qXLE5Zvz1B1z6f06I+VMwQWjNMPo9JeA5iuyL5O+wVYDlpBsoUnY38Vsw6vLYmQNb8nnGfo1Sonu5W9O3gUTVNKVDB6F4qJLDLCgVVWXdmJGvC8qVg3n+ggbT/5yiMh6nmaLeqLMPZZViMn52jAVbIJQvcWTvttUwdH9Qpf3m7aJdpP834XPcvnrWSBg4TyOdG/M5SyJFFXDIgFQNsj6UoGEqADDi9pB1eAO/iwGGB7tciD4x/yrkHgqMd0XJPDOVZzr1h2v7IHhOtbh3szXcaGJNTwMqiwC6ihtgips1MJahpaky73VUDMWcnggoaTSOOJvEPZ8SNhgyec0wj6UhpDp9uJYbdxWFcf8ad97l9EesoyfOzIbyoS7SqpFDS/+JZFvb7MaZV8v3AQkJkr/SWs74vz3Nng6rbF8IANK7yDuoEf8LmwwZJtbXoCaZmsERt73ZprdRWztDX4n7PdF/7mJ37yVg/W4+2vPm8FqQ5BE1BwcgwTNd7/QJyhNTcNvm/BDIgZ4o/78KhQUxRsiBP85ck2WcvDf9hKlS+xixom7qY4PazAVWMRhvefg99ANuj1r3o38sTMlYOf",
"id": "46fed882-98da-497f-8400-9c92f4c66bb0",
"crc": "0xda95",
"name": "MCastCounter"
},
{
"size": 2785,
"file": "/d9CprNlBqsxQ8oJ+23SCfkIrXOaoUIaxHNoVK5xo3FLuS9uDXBRO1ommFU6wmMvssqK13qPGMFBe7gc/IaZY8c6fK0KnAgY/WPZWAsQGi1xDP+L7hoi8J0lts3BCJ1czjzCE9y4H176wcKqyezON3FW/0HvYJG9WpgR18eKFe6mW3ylE5QAltxIQG8jQBlXsOU82J7G8mdsds9prCbC8A2Vqiekmgza4Q7l6MnStBilePZxqhYipsWnifMiq4UsHatKcnfZd7ohnf49wQLMS8h1t3R/WYcYfJy7VSso8g6wJ8K5LRv1l3AH1qE9ohJERfc7C1aWAq/ApYIVTBxcFt6yuytjskB1QWoXoQ6l+9qmR//H8KiQbWcw6D/j5FBW61Py1ZHU45r66FSP1FeqjCv9dwGx5qkF9OSM0g9bsObdahldQ1nS1xdV+Zg/RkVSAeeMmrFqg3tTPLslRbckDW6kj/F/KZaiqrAjjK25REMjcEv9aRg8lBiwqvxLcAev6Kd3KKH27rlqH3WhbrYBe4AUFw7kNgjPQ3gIX8jf0HJOl3PZO32FuJksQfjvO7xW94sXC0BUbXrszZ+WDKMY4rmN2YGHflE9L+yChq/DpKSuG2eahqLb915osWahSDd2RQ27aQ3SDXwd8jKwAjpxKR0FWxp8yLDgoIUFJwWJBjyun+4f+qXLE5Zvz1B1z6f06I+VMwQWjNMPo9JeA5iuyL5O+wVYDlpBsoUnY38Vsw6vLYmQNb8nnGfo1Sonu5W9O3gUTVNKVDB6F4qJLDLCgVVWXdmJGvC8qVg3n+ggbT/5yiMh6nmaLeqLMPZZViMn52jAVbIJQvcWTvttUwdH9Qpf3m7aJdpP834XPcvnrWSBg4TyOdG/M5SyJFFXDIgFQNsj6UoGEqADDi9pB1eAO/iwGGB7tciD4x/yrkHgqMd0XJPDOVZzr1h2v7IHhOtbh3szXcaGJNTwMqiwC6ihtgips1MJahpaky73VUDMWcnggoaTSOOJvEPZ8SNhgyec0wj6UhpDp9uJYbdxWFcf8ad97l9EesoyfOzIbyoS7SqpFDS/+JZFvb7MaZV8v3AQkJkr/SWs74vz3Nng6rbF8IANK7yDuoEf8LmwwZJtbXoCaZmsERt73ZprdRWztDX4n7PdF/7mJ37yVg/W4+2vPm8FqQ5BE1BwcgwTNd7/QJyhNTcNvm/BDIgZ4o/78KhQUxRsiBP85ck2WcvDf9hKlS+xixom7qY4PazAVWMRhvefg99ANuj1r3o38sTMlYOf",
"id": "12abc882-98da-497f-8400-9c92f4c66bb0",
"crc": "0xda95",
"name": "BlinkLED"
}
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"dataCollectors": {
"items": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"deviceTypes": {
"items": {
"properties": {
"description": {
"description": "Name of device type",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"images": {
"items": {
"properties": {
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"file": {
"description": "SPY image content",
"type": "string"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
},
"crc": {
"description": "Checksum of SPY image content",
"type": "string"
},
"name": {
"description": "The script name compiled into the SPY image",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
"type": "object"
}Import site configurationPOST/api/v1/siteConfig
Example URI
POST /api/v1/siteConfig
Request
Body
{}Schema
{
"required": [
"deviceTypes",
"dataCollectors",
"images"
],
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"dataCollectors": {
"description": {
"description": "Data collectors",
"type": "object"
}
},
"deviceTypes": {
"description": {
"description": "Device types",
"type": "object"
}
},
"images": {
"description": {
"description": "Images",
"type": "object"
}
}
},
"type": "object"
}Response
201The site configuration was successfully imported.
Body
{
"dataCollectors": [
{
"dataCollectorType": "asynchronous",
"deviceTypes": [
"sensors"
],
"initRpcName": "setReceiverAddress",
"name": "dc1",
"dataRpcName": "acceptData"
},
{
"queryFunction": "data",
"dataCollectorType": "synchronous",
"deviceTypes": [
"lights"
],
"pollInterval": 60,
"name": "dc2"
}
],
"deviceTypes": [
{
"description": "a device type description"
},
{
"description": "another device type description"
}
],
"images": [
{
"size": 3489,
"file": "/d9CprNlBqsxQ8oJ+23SCfkIrXOaoUIaxHNoVK5xo3FLuS9uDXBRO1ommFU6wmMvssqK13qPGMFBe7gc/IaZY8c6fK0KnAgY/WPZWAsQGi1xDP+L7hoi8J0lts3BCJ1czjzCE9y4H176wcKqyezON3FW/0HvYJG9WpgR18eKFe6mW3ylE5QAltxIQG8jQBlXsOU82J7G8mdsds9prCbC8A2Vqiekmgza4Q7l6MnStBilePZxqhYipsWnifMiq4UsHatKcnfZd7ohnf49wQLMS8h1t3R/WYcYfJy7VSso8g6wJ8K5LRv1l3AH1qE9ohJERfc7C1aWAq/ApYIVTBxcFt6yuytjskB1QWoXoQ6l+9qmR//H8KiQbWcw6D/j5FBW61Py1ZHU45r66FSP1FeqjCv9dwGx5qkF9OSM0g9bsObdahldQ1nS1xdV+Zg/RkVSAeeMmrFqg3tTPLslRbckDW6kj/F/KZaiqrAjjK25REMjcEv9aRg8lBiwqvxLcAev6Kd3KKH27rlqH3WhbrYBe4AUFw7kNgjPQ3gIX8jf0HJOl3PZO32FuJksQfjvO7xW94sXC0BUbXrszZ+WDKMY4rmN2YGHflE9L+yChq/DpKSuG2eahqLb915osWahSDd2RQ27aQ3SDXwd8jKwAjpxKR0FWxp8yLDgoIUFJwWJBjyun+4f+qXLE5Zvz1B1z6f06I+VMwQWjNMPo9JeA5iuyL5O+wVYDlpBsoUnY38Vsw6vLYmQNb8nnGfo1Sonu5W9O3gUTVNKVDB6F4qJLDLCgVVWXdmJGvC8qVg3n+ggbT/5yiMh6nmaLeqLMPZZViMn52jAVbIJQvcWTvttUwdH9Qpf3m7aJdpP834XPcvnrWSBg4TyOdG/M5SyJFFXDIgFQNsj6UoGEqADDi9pB1eAO/iwGGB7tciD4x/yrkHgqMd0XJPDOVZzr1h2v7IHhOtbh3szXcaGJNTwMqiwC6ihtgips1MJahpaky73VUDMWcnggoaTSOOJvEPZ8SNhgyec0wj6UhpDp9uJYbdxWFcf8ad97l9EesoyfOzIbyoS7SqpFDS/+JZFvb7MaZV8v3AQkJkr/SWs74vz3Nng6rbF8IANK7yDuoEf8LmwwZJtbXoCaZmsERt73ZprdRWztDX4n7PdF/7mJ37yVg/W4+2vPm8FqQ5BE1BwcgwTNd7/QJyhNTcNvm/BDIgZ4o/78KhQUxRsiBP85ck2WcvDf9hKlS+xixom7qY4PazAVWMRhvefg99ANuj1r3o38sTMlYOf",
"id": "46fed882-98da-497f-8400-9c92f4c66bb0",
"crc": "0xda95",
"name": "MCastCounter"
},
{
"size": 2785,
"file": "/d9CprNlBqsxQ8oJ+23SCfkIrXOaoUIaxHNoVK5xo3FLuS9uDXBRO1ommFU6wmMvssqK13qPGMFBe7gc/IaZY8c6fK0KnAgY/WPZWAsQGi1xDP+L7hoi8J0lts3BCJ1czjzCE9y4H176wcKqyezON3FW/0HvYJG9WpgR18eKFe6mW3ylE5QAltxIQG8jQBlXsOU82J7G8mdsds9prCbC8A2Vqiekmgza4Q7l6MnStBilePZxqhYipsWnifMiq4UsHatKcnfZd7ohnf49wQLMS8h1t3R/WYcYfJy7VSso8g6wJ8K5LRv1l3AH1qE9ohJERfc7C1aWAq/ApYIVTBxcFt6yuytjskB1QWoXoQ6l+9qmR//H8KiQbWcw6D/j5FBW61Py1ZHU45r66FSP1FeqjCv9dwGx5qkF9OSM0g9bsObdahldQ1nS1xdV+Zg/RkVSAeeMmrFqg3tTPLslRbckDW6kj/F/KZaiqrAjjK25REMjcEv9aRg8lBiwqvxLcAev6Kd3KKH27rlqH3WhbrYBe4AUFw7kNgjPQ3gIX8jf0HJOl3PZO32FuJksQfjvO7xW94sXC0BUbXrszZ+WDKMY4rmN2YGHflE9L+yChq/DpKSuG2eahqLb915osWahSDd2RQ27aQ3SDXwd8jKwAjpxKR0FWxp8yLDgoIUFJwWJBjyun+4f+qXLE5Zvz1B1z6f06I+VMwQWjNMPo9JeA5iuyL5O+wVYDlpBsoUnY38Vsw6vLYmQNb8nnGfo1Sonu5W9O3gUTVNKVDB6F4qJLDLCgVVWXdmJGvC8qVg3n+ggbT/5yiMh6nmaLeqLMPZZViMn52jAVbIJQvcWTvttUwdH9Qpf3m7aJdpP834XPcvnrWSBg4TyOdG/M5SyJFFXDIgFQNsj6UoGEqADDi9pB1eAO/iwGGB7tciD4x/yrkHgqMd0XJPDOVZzr1h2v7IHhOtbh3szXcaGJNTwMqiwC6ihtgips1MJahpaky73VUDMWcnggoaTSOOJvEPZ8SNhgyec0wj6UhpDp9uJYbdxWFcf8ad97l9EesoyfOzIbyoS7SqpFDS/+JZFvb7MaZV8v3AQkJkr/SWs74vz3Nng6rbF8IANK7yDuoEf8LmwwZJtbXoCaZmsERt73ZprdRWztDX4n7PdF/7mJ37yVg/W4+2vPm8FqQ5BE1BwcgwTNd7/QJyhNTcNvm/BDIgZ4o/78KhQUxRsiBP85ck2WcvDf9hKlS+xixom7qY4PazAVWMRhvefg99ANuj1r3o38sTMlYOf",
"id": "12abc882-98da-497f-8400-9c92f4c66bb0",
"crc": "0xda95",
"name": "BlinkLED"
}
]
}Schema
{
"properties": {
"data": {
"properties": {
"dataCollectors": {
"items": {
"properties": {
"initRpcName": {
"description": "Name of function implemented by SNAPpy script (async only)",
"type": "string"
},
"queryFunction": {
"description": "Name of query function (sync only)",
"type": "string"
},
"name": {
"description": "Name of data collector",
"type": "string"
},
"pollInterval": {
"description": "Number of seconds between polls (sync only)",
"type": "integer"
},
"dataCollectorType": {
"description": "Data collector type, one of 'synchronous' or 'asynchronous'",
"type": "string"
},
"deviceTypes": {
"items": {
"description": "Description of device type",
"type": "string"
},
"type": "array"
},
"dataRpcName": {
"description": "Name of the RPC that the receiver will listen on for new data (async only)",
"type": "string"
},
"href": {
"description": "URI for this data collector resource",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"deviceTypes": {
"items": {
"properties": {
"description": {
"description": "Name of device type",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"images": {
"items": {
"properties": {
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"crc": {
"description": "Checksum of SPY image content",
"type": "string"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
},
"href": {
"description": "URI 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"
}
},
"type": "object"
}Response
400Site configuration could not be imported with these attributes.
Body
{
"error": {
"message": "Site configuration could not be imported with these attributes"
}
}Schema
{
"properties": {
"error": {
"properties": {
"message": {
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}SPY Images ¶
SPY Image Collection ¶
Get all SPY imagesGET/api/v1/images
Example URI
GET /api/v1/images
Response
200List all images.If no SPY images have been uploaded, the response contains an empty array.
Body
{
"data": [
{
"size": 3489,
"crc": "0xda95",
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"name": "McastCounter"
},
{
"size": 690,
"crc": "0x16f1",
"id": "f97fdf18-fede-4d58-96d4-eb3f36b4b872",
"href": "https://localhost:3000/api/v1/images/f97fdf18-fede-4d58-96d4-eb3f36b4b872",
"name": "blink"
}
]
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"href": {
"description": "URI for this SPY image resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
},
"crc": {
"description": "Checksum of SPY image content",
"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
{
"title": "Upload SPY image",
"properties": {
"content": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"description": "Base64-encoded SPY image contents",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"content"
],
"description": "A SPY file image",
"type": "object"
}Response
201Successfully created image.
Headers
Location: https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915dBody
{
"data": {
"size": 3489,
"crc": "0xda95",
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"name": "McastCounter"
}
}Schema
{
"properties": {
"data": {
"properties": {
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"href": {
"description": "URI for this SPY image resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
},
"crc": {
"description": "Checksum of SPY image content",
"type": "string"
},
"name": {
"description": "The script name compiled into the SPY image",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
}Delete all SPY imagesDELETE/api/v1/images
Example URI
DELETE /api/v1/images
Response
204Successfully deleted all images.
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
200Get image details.
Body
{
"data": {
"size": 3489,
"crc": "0xda95",
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"name": "McastCounter"
}
}Schema
{
"properties": {
"data": {
"items": {
"properties": {
"size": {
"description": "Image size in bytes",
"type": "integer"
},
"href": {
"description": "URI for this SPY image resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this SPY image resource",
"type": "string"
},
"crc": {
"description": "Checksum of SPY image content",
"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
204Successfully deleted image.
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
200List all 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
200List all network configurations.
Body
{
"data": [
{
"id": "7e968754-78f0-09f8-b57b-968745b2789e",
"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": "c5fe2546-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"
]
}
]
}
]
}Schema
{
"properties": {
"data": {
"items": {
"description": "A network configuration resource",
"properties": {
"id": {
"description": "Unique identifier for this network configuration resource",
"type": "string"
},
"href": {
"description": "URI for this network configuration resource",
"type": "string"
},
"deviceGroupConfigurations": {
"items": {
"description": "Associates a configuration with a group of devices",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"properties": {
"firmware": {
"description": "A SNAP firmware release",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
},
"image": {
"description": "A SPY image",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"devices": {
"items": {
"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]$",
"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').",
"description": "SNAP MAC address",
"type": "string"
},
"description": "A group of devices",
"uniqueItems": true,
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"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
{
"title": "Add network configuration",
"properties": {
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"description": "Associates a configuration with a group of devices",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"properties": {
"firmware": {
"description": "A SNAP firmware release",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
},
"image": {
"description": "A SPY image",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"devices": {
"items": {
"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]$",
"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\").",
"description": "SNAP MAC address",
"type": "string"
},
"description": "A group of devices",
"uniqueItems": true,
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"deviceGroupConfigurations"
],
"description": "A network configuration resource",
"type": "object"
}Response
201Successfully created network configuration.
Headers
Location: https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789eBody
{
"data": {
"id": "7e968754-78f0-09f8-b57b-968745b2789e",
"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"
]
}
]
}
}Schema
{
"properties": {
"data": {
"required": [
"deviceGroupConfigurations"
],
"description": "A network configuration resource",
"properties": {
"id": {
"description": "Unique identifier for this network configuration resource",
"type": "string"
},
"href": {
"description": "URI for this network configuration resource",
"type": "string"
},
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"description": "Associates a configuration with a group of devices",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"properties": {
"firmware": {
"description": "A SNAP firmware release",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
},
"image": {
"description": "A SPY image",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"devices": {
"items": {
"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]$",
"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').",
"description": "SNAP MAC address",
"type": "string"
},
"description": "A group of devices",
"uniqueItems": true,
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"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
200Get network configuration details.
Body
{
"data": {
"id": "7e968754-78f0-09f8-b57b-968745b2789e",
"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"
]
}
]
}
}Schema
{
"properties": {
"data": {
"required": [
"deviceGroupConfigurations"
],
"description": "A network configuration resource",
"properties": {
"id": {
"description": "Unique identifier for this network configuration resource",
"type": "string"
},
"href": {
"description": "URI for this network configuration resource",
"type": "string"
},
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"description": "Associates a configuration with a group of devices",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"properties": {
"firmware": {
"description": "A SNAP firmware release",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
},
"image": {
"description": "A SPY image",
"properties": {
"href": {
"description": "Location",
"type": "string"
}
},
"type": "object"
}
},
"type": "object"
},
"devices": {
"items": {
"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]$",
"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').",
"description": "SNAP MAC address",
"type": "string"
},
"description": "A group of devices",
"uniqueItems": true,
"type": "array"
}
},
"type": "object"
},
"type": "array"
}
},
"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
{
"title": "Apply a network configuration update",
"properties": {
"href": {
"description": "The location of a network configuration",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"href"
],
"description": "A network configuration location",
"type": "object"
}Response
202Accepted network configuration update for processing.
Headers
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 description identifies multiple devices but the user’s license restricts them to upgrading only one device 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
200Get network configuration update results.
Body
{
"data": {
"image_results": [
{
"result": "success",
"address": "60866a"
},
{
"result": "success",
"address": "608477"
}
],
"id": "9496aed3-1614-4207-8883-2c807958d940",
"href": "https://localhost:3000/api/v1/networkConfigurationUpdates/9496aed3-1614-4207-8883-2c807958d940",
"firmware_results": [
{
"result": "failure",
"address": "60866a"
},
{
"result": "success",
"address": "608477"
}
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"image_results": {
"items": {
"properties": {
"result": {
"description": "Outcome of the attempted update, either success or failure",
"type": "string"
},
"address": {
"description": "MAC address for the device described in this result",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"id": {
"description": "Unique identifier for this results set",
"type": "string"
},
"href": {
"description": "URI for this network configuration update results resource",
"type": "string"
},
"firmware_results": {
"items": {
"properties": {
"result": {
"description": "Outcome of the attempted update, either success or failure",
"type": "string"
},
"address": {
"description": "MAC address for the device described in this result",
"type": "string"
}
},
"type": "object"
},
"type": "array"
}
},
"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": {
"id": "8ba8d8bd-edeb-4960-bb05-87c75697bf6d",
"href": "https://localhost:3000/api/v1/tasks/8ba8d8bd-edeb-4960-bb05-87c75697bf6d"
}
}Schema
{
"properties": {
"data": {
"properties": {
"id": {
"description": "Unique identifier for this task",
"type": "string"
},
"href": {
"description": "URI of this task resource",
"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
200Get TCP access details.
Body
{
"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
{
"username": "snap",
"password": "Synapse$0123"
}Schema
{
"title": "Add device type",
"properties": {
"username": {
"minLength": 1,
"description": "Username for the TCP connection",
"type": "string"
},
"password": {
"minLength": 1,
"description": "Password for the TCP connection",
"type": "string"
}
},
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"username",
"password"
],
"description": "A device type",
"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
204Successfully disabled TCP
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
200List all topologies.
Body
{
"data": [
{
"href": "https://localhost:3000/api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"links": [
{
"end": "5ecad4",
"start": "608509",
"linkQuality": 71
},
{
"end": "608509",
"start": "5ecad4",
"linkQuality": 68
}
],
"createdAt": "2016-07-27T13:57:43.361554Z",
"gateways": [
"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"
},
"links": {
"items": {
"properties": {
"end": {
"description": "End address for this link",
"type": "string"
},
"start": {
"description": "Start address for this link",
"type": "string"
},
"linkQuality": {
"description": "Link quality for this link (-dBm)",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"createdAt": {
"description": "Topology creation date (ISO8601 format)",
"type": "string"
},
"gateways": {
"items": {
"description": "Gateway MAC address",
"type": "string"
},
"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
202Accepted topology for processing.
Headers
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
204Successfully deleted all topologies.
SNAP 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
200Get topology details.
Body
{
"data": {
"href": "https://localhost:3000/api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
"links": [
{
"end": "5ecad4",
"start": "608509",
"linkQuality": 71
},
{
"end": "608509",
"start": "5ecad4",
"linkQuality": 68
}
],
"createdAt": "2016-07-27T13:57:43.361554Z",
"gateways": [
"608509"
]
}
}Schema
{
"properties": {
"data": {
"properties": {
"href": {
"description": "URI for this topology resource",
"type": "string"
},
"id": {
"description": "Unique identifier for this topology resource",
"type": "string"
},
"links": {
"items": {
"properties": {
"end": {
"description": "End address for this link",
"type": "string"
},
"start": {
"description": "Start address for this link",
"type": "string"
},
"linkQuality": {
"description": "Link quality for this link (-dBm)",
"type": "integer"
}
},
"type": "object"
},
"type": "array"
},
"createdAt": {
"description": "Topology creation date (ISO8601 format)",
"type": "string"
},
"gateways": {
"items": {
"description": "Gateway MAC address",
"type": "string"
},
"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
204Successfully deleted topology.
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"
}Topology Generation State ¶
Handles requests for topology generation currently in progress or not.
Get topology generation stateGET/api/v1/topologyInProgress
Example URI
GET /api/v1/topologyInProgress
Response
200Successfully retrieved topology progress
Body
{
"data": true
}Schema
{
"properties": {
"data": {
"description": "Indicates whether topology generation is in progress",
"type": "boolean"
}
},
"type": "object"
}