SNAP Thing Services API
SNAP Thing Services API Version 1.8.2
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
{
"required": [
"old",
"new"
],
"title": "Update device",
"description": "A device",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"new": {
"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",
"description": "New password"
},
"old": {
"type": "string",
"description": "Old password"
}
}
}Response
200Successfully updated password.
Body
{
"data": "Successfully changed password"
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "string"
}
}
}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
{
"type": "object",
"properties": {
"error": {
"message": {
"type": "string"
},
"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
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"isActuationEnabled": {
"type": "boolean",
"description": "true or false"
}
}
}
}
}Used to toggle actuation requestPOST/api/v1/actuation/config
Example URI
POST /api/v1/actuation/config
Request
Body
{
"isActuationEnabled": false
}Schema
{
"required": [
"isActuationEnabled"
],
"title": "Toggle Actuation for devices",
"description": "Toggle Actuation for devices",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"isActuationEnabled": {
"type": "boolean",
"description": "True or False"
}
}
}Response
200actuation enabled status
Body
{
"data": {
"isActuationEnabled": true
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"isActuationEnabled": {
"type": "boolean",
"description": "true or false"
}
}
}
}
}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": [
{
"devices": [
"098231",
"09a1b4"
],
"results": [
{
"address": "098231",
"result": "success"
},
{
"address": "09a1b4",
"result": "failure"
}
],
"deviceTypes": [],
"function": "light_level",
"parameters": [
256
],
"finishedAt": "2017-01-12T08:50:21.846736",
"startedAt": "2017-01-12T08:50:21.726736",
"createdAt": "2017-01-12T08:50:21.506736",
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/actuation/requests/6f992502-33f0-47d4-a01e-973593e1915d",
"status": "Completed With Errors"
},
{
"devices": [],
"results": [
{
"address": "098231",
"result": "success"
}
],
"deviceTypes": [
"devicetype1"
],
"function": "actuate_me",
"parameters": [],
"finishedAt": "2017-01-10T08:50:21.846736",
"startedAt": "2017-01-10T08:50:21.726736",
"createdAt": "2017-01-10T08:50:21.506736",
"id": "7r592502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/actuation/requests/7r592502-33f0-47d4-a01e-973593e1915d",
"status": "Completed"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"devices": {
"items": {
"type": "string",
"description": "List of device MAC addresses"
},
"type": "array"
},
"results": {
"type": "string",
"description": "Result of actuation request"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "List of name of device type"
},
"type": "array"
},
"function": {
"type": "string",
"description": "Function Name"
},
"parameters": {
"items": {
"anyOf": [
{
"type": [
"string",
"boolean",
"null",
"integer"
]
}
],
"description": "List of parameters"
},
"type": "array"
},
"finishedAt": {
"type": "string",
"description": "Time at which actuation finished"
},
"startedAt": {
"type": "string",
"description": "Time at which actuation started"
},
"createdAt": {
"type": "string",
"description": "Time at which actuation initiated"
},
"id": {
"type": "string",
"description": "Unique identifier for this actuation"
},
"href": {
"type": "string",
"description": "URI for this actuation result"
},
"status": {
"type": "string",
"description": "Status of the actuation request"
}
}
},
"type": "array"
}
}
}Creates new actuation requestPOST/api/v1/actuation/requests
Example URI
POST /api/v1/actuation/requests
Request
Body
{
"deviceTypes": [
"thesedevices",
"thosedevices"
],
"parameters": [
"<stringval>",
1,
null,
true
],
"function": "actuate_me",
"devices": [
"0600a3",
"0833a4",
"0534fe"
]
}Schema
{
"required": [
"function"
],
"title": "Actuate devices",
"description": "Actuate devices",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"deviceTypes": {
"items": {
"type": "string",
"description": "List of types of device. This must exist in the database already."
},
"type": "array"
},
"parameters": {
"items": {
"anyOf": [
{
"type": [
"string",
"boolean",
"null",
"integer"
]
}
]
},
"type": "array"
},
"function": {
"pattern_description": "Actuation functions must be valid public SNAPpy functions. (ex: 'data', 'actuate_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string",
"description": "SNAPpy script function"
},
"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]$",
"type": "string",
"description": "SNAP MAC address"
},
"type": "array"
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}Response
400Parameter string should be base64 encoded
Body
{
"error": {
"message": "Parameter string should be base64 encoded"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": {
"devices": [],
"results": [
{
"address": "60866a",
"result": "failure"
},
{
"address": "608477",
"result": "success"
}
],
"deviceTypes": [
"devicetype1"
],
"function": "actuate_me",
"parameters": [],
"finishedAt": "2017-01-10T08:50:21.846736",
"startedAt": "2017-01-10T08:50:21.726736",
"createdAt": "2017-01-10T08:50:21.506736",
"id": "e00667ce-78b5-4595-8288-3ff0e50ed147",
"href": "https://localhost:3000/api/v1/actuation/requests/e00667ce-78b5-4595-8288-3ff0e50ed147",
"status": "Completed With Errors"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"devices": {
"items": {
"type": "string",
"description": "List of device MAC addresses"
},
"type": "array"
},
"results": {
"items": {
"address": {
"type": "string",
"description": "MAC address for the device described in this result"
},
"result": {
"type": "string",
"description": "Outcome of the attempted actuation, either success or failure"
}
},
"type": "array"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "List of device type descriptions"
},
"type": "array"
},
"function": {
"type": "string",
"description": "Name of the function"
},
"parameters": {
"items": {
"anyOf": [
{
"type": [
"string",
"boolean",
"null",
"integer"
]
}
],
"description": "List of parameters"
},
"type": "array"
},
"finishedAt": {
"type": "string",
"description": "Time at which actuation finished"
},
"startedAt": {
"type": "string",
"description": "Time at which actuation started"
},
"createdAt": {
"type": "string",
"description": "Time at which actuation initiated"
},
"id": {
"type": "integer",
"description": "Unique identifier for this device type"
},
"href": {
"type": "string",
"description": "URI for this device type resource"
},
"status": {
"type": "string",
"description": "Status of the actuation request"
}
}
},
"type": "array"
}
}
}Response
404No such result.
Body
{
"error": {
"message": "Actuation result could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"message": {
"type": "string"
},
"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": {
"configured_settings": {
"rpcCrc": false,
"networkId": "0x3ab3",
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"encryptionType": "AES-128",
"channel": 10,
"packetCrc": true
},
"bridge_addr": "012345",
"actual_settings": {
"rpcCrc": false,
"networkId": "0x3ab3",
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"encryptionType": "AES-128",
"channel": 10,
"packetCrc": true
}
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"configured_settings": {
"properties": {
"rpcCrc": {
"type": "boolean",
"description": "Indicates whether the RPC CRC packet integrity check should be enabled"
},
"networkId": {
"type": "string",
"description": "The network identifier (ex: '0x1c2c')"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"type": "string",
"description": "The Base64 encoded encryption key"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"channel": {
"type": "integer",
"description": "The RF channel"
},
"packetCrc": {
"type": "boolean",
"description": "Indicates whether packet-level CRC validation should be enabled"
}
},
"type": "object",
"description": "Configured network settings"
},
"bridge_addr": {
"type": "string",
"description": "Device MAC address"
},
"actual_settings": {
"properties": {
"rpcCrc": {
"type": "boolean",
"description": "Indicates whether the RPC CRC packet integrity check is enabled"
},
"networkId": {
"type": "string",
"description": "The network identifier (ex: '0x1c2c')"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"type": "string",
"description": "The Base64 encoded encryption key"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"channel": {
"type": "integer",
"description": "The RF channel"
},
"packetCrc": {
"type": "boolean",
"description": "Indicates whether packet-level CRC validation is enabled"
}
},
"type": "object",
"description": "Actual bridge node network settings"
}
}
}
}
}Response
400Could not get network settings.
Body
{
"apiVersion": "v1",
"error": {
"message": "Could not get network settings",
"code": 400
}
}Schema
{
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "integer",
"description": "HTTP response status"
}
}
}
}
}Update the current network settingsPUT/api/v1/network
Example URI
PUT /api/v1/network
Request
Body
{
"rpcCrc": false,
"networkId": "0x3ab3",
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"encryptionType": "AES-128",
"channel": 10,
"packetCrc": true
}Schema
{
"required": [
"channel",
"networkId",
"rpcCrc",
"packetCrc",
"encryptionType",
"encryptionKey"
],
"title": "Update network settings",
"description": "A group of network settings",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"rpcCrc": {
"type": "boolean",
"description": "Indicates whether the RPC CRC packet integrity check should be enabled"
},
"networkId": {
"type": "string",
"description": "The network identifier (ex: '0x1c2c')"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"type": "string",
"description": "The Base64 encoded encryption key"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"channel": {
"type": "integer",
"description": "The RF channel"
},
"packetCrc": {
"type": "boolean",
"description": "Indicates whether packet-level CRC validation should be enabled"
}
}
}Response
200Successfully updated network settings.
Headers
Content-Type: application/jsonBody
{
"data": {
"rpcCrc": false,
"networkId": "0x3ab3",
"encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
"encryptionType": "AES-128",
"channel": 10,
"packetCrc": true
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"rpcCrc": {
"type": "boolean",
"description": "Indicates whether the RPC CRC packet integrity check is enabled"
},
"networkId": {
"type": "string",
"description": "The network identifier (ex: '0x1c2c')"
},
"encryptionKey": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"type": "string",
"description": "The Base64 encoded encryption key"
},
"encryptionType": {
"enum": [
"None",
"AES-128",
"Basic"
],
"description": "The type of encryption used to communicate"
},
"channel": {
"type": "integer",
"description": "The RF channel"
},
"packetCrc": {
"type": "boolean",
"description": "Indicates whether packet-level CRC validation is enabled"
}
}
}
}
}Response
400Could not update network settings.
Body
{
"apiVersion": "v1",
"error": {
"message": "Could not update network settings",
"code": 400
}
}Schema
{
"type": "object",
"properties": {
"apiVersion": {
"type": "string"
},
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "integer",
"description": "HTTP response status"
}
}
}
}
}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": [
{
"deviceTypes": [
"sensors"
],
"id": 1,
"name": "dc1",
"dataRpcName": "acceptData",
"data_collector_type": "asynchronous",
"initRpcName": "setReceiverAddress",
"href": "https://localhost:3000/api/v1/dc/dc1"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"queryFunction": {
"type": "string",
"description": "Name of query function (sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"initRpcName": {
"type": "string",
"description": "Name of function implemented by SNAPpy script (async only)"
},
"name": {
"type": "string",
"description": "Name of data collector"
},
"dataRpcName": {
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (async only)"
},
"pollInterval": {
"type": "integer",
"description": "Number of seconds between polls (sync only)"
},
"id": {
"type": "integer",
"description": "Unique identifier for this data collector"
},
"href": {
"type": "string",
"description": "URI for this data collector resource"
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
},
"type": "array"
}
}
}Create a data collectorPOST/api/v1/dc
Example URI
POST /api/v1/dc
Request
Body
{
"deviceTypes": [
"sensors"
],
"queryFunction": "data",
"dataCollectorType": "synchronous",
"pollInterval": 60,
"name": "dc1"
}Schema
{
"required": [
"name",
"deviceTypes"
],
"title": "Add data collector",
"description": "A data collector",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"queryFunction": {
"pattern_description": "Query functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string",
"description": "Name of query function (required for sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"name": {
"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",
"description": "Name of data collector"
},
"dataRpcName": {
"pattern_description": "Data functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (required for async only)"
},
"pollInterval": {
"minimum": 5,
"description": "Number of seconds between polls (required for sync only)",
"type": "integer",
"maximum": 86400
},
"initRpcName": {
"anyOf": [
{
"pattern_description": "Init functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string",
"description": "Name of function implemented by SNAPpy script (required for async only)"
},
{
"type": "null"
}
]
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
}Response
201Successfully created data collector.
Body
{
"data": {
"deviceTypes": [
"sensors"
],
"id": 1,
"name": "dc1",
"dataRpcName": "acceptData",
"initRpcName": "setReceiverAddress",
"href": "https://localhost:3000/api/v1/dc/dc1",
"dataCollectorType": "asynchronous"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"queryFunction": {
"type": "string",
"description": "Name of query function (sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"initRpcName": {
"type": "string",
"description": "Name of function implemented by SNAPpy script (async only)"
},
"name": {
"type": "string",
"description": "Name of data collector"
},
"dataRpcName": {
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (async only)"
},
"pollInterval": {
"type": "integer",
"description": "Number of seconds between polls (sync only)"
},
"id": {
"type": "integer",
"description": "Unique identifier for this data collector"
},
"href": {
"type": "string",
"description": "URI for this data collector resource"
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
}
}
}Response
409A data collector with this name already exists.
Body
{
"error": {
"message": "A data collector with this name already exists"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": {
"queryFunction": "data",
"deviceTypes": [
"sensors"
],
"name": "dc1",
"pollInterval": 60,
"id": 1,
"href": "https://localhost:3000/api/v1/dc/dc1",
"dataCollectorType": "synchronous"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"queryFunction": {
"type": "string",
"description": "Name of query function (sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"initRpcName": {
"type": "string",
"description": "Name of function implemented by SNAPpy script (async only)"
},
"name": {
"type": "string",
"description": "Name of data collector"
},
"dataRpcName": {
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (async only)"
},
"pollInterval": {
"type": "integer",
"description": "Number of seconds between polls (sync only)"
},
"id": {
"type": "integer",
"description": "Unique identifier for this data collector"
},
"href": {
"type": "string",
"description": "URI for this data collector resource"
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
}
}
}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
{
"deviceTypes": [
"sensors"
],
"dataRpcName": "acceptData",
"name": "dc1",
"dataCollectorType": "asynchronous",
"initRpcName": "setReceiverAddress"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "A data collector",
"title": "Update a data collector",
"type": "object",
"properties": {
"queryFunction": {
"pattern_description": "Query functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string",
"description": "Name of query function (required for sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"name": {
"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",
"description": "Name of data collector"
},
"dataRpcName": {
"pattern_description": "Data functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (required for async only)"
},
"pollInterval": {
"minimum": 5,
"description": "Number of seconds between polls (required for sync only)",
"type": "integer",
"maximum": 86400
},
"initRpcName": {
"anyOf": [
{
"pattern_description": "Init functions must be valid public SNAPpy functions. (ex: 'data', 'query_2B')",
"pattern": "^[a-zA-Z]\\w*$",
"type": "string",
"description": "Name of function implemented by SNAPpy script (required for async only)"
},
{
"type": "null"
}
]
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
}Response
200Successfully updated data collector.
Body
{
"data": {
"deviceTypes": [
"sensors"
],
"id": 1,
"name": "dc1",
"dataRpcName": "acceptData",
"initRpcName": "setReceiverAddress",
"href": "https://localhost:3000/api/v1/dc/dc1",
"dataCollectorType": "asynchronous"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"queryFunction": {
"type": "string",
"description": "Name of query function (sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"initRpcName": {
"type": "string",
"description": "Name of function implemented by SNAPpy script (async only)"
},
"name": {
"type": "string",
"description": "Description of data collector type"
},
"dataRpcName": {
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (async only)"
},
"pollInterval": {
"type": "integer",
"description": "Number of seconds between polls (sync only)"
},
"id": {
"type": "integer",
"description": "Unique identifier for this data collector"
},
"href": {
"type": "string",
"description": "URI for this data collector resource"
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
}
}
}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": [
{
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
},
"firmware": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1"
},
"platform": "RF200",
"upgrading": false,
"addr": "aabbcc",
"id": 2,
"href": "https://localhost:3000/api/v1/devices/2",
"description": "test",
"deviceType": "Deck1"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"image": {
"properties": {
"href": {
"type": "string",
"description": "URI for this image resource"
}
},
"type": "object",
"description": "Software on device"
},
"firmware": {
"properties": {
"href": {
"type": "string",
"description": "URI for this firmware resource"
},
"requiresUpgrade": {
"type": "boolean",
"description": "Indicates whether firmware requires an upgrade"
}
},
"type": "object",
"description": "Firmware on device"
},
"platform": {
"type": "string",
"description": "Hardware platform"
},
"upgrading": {
"type": "boolean",
"description": "Indicates whether device is upgrading"
},
"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]$",
"type": "string",
"description": "Device MAC address"
},
"id": {
"type": "integer",
"description": "Unique identifier for this device"
},
"href": {
"type": "string",
"description": "URI for this device resource"
},
"description": {
"type": "string",
"description": "User defined name for the device"
},
"deviceType": {
"type": "string",
"description": "Device type"
}
}
},
"type": "array"
}
}
}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",
"platform": "RF200",
"deviceType": "Deck1",
"description": "Device1"
}Schema
{
"required": [
"addr",
"description",
"deviceType"
],
"title": "Add device",
"description": "A device",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Description of the device"
},
"deviceType": {
"type": "string",
"description": "The type of device. This must exist in the database already."
},
"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]$",
"type": "string",
"description": "SNAP MAC address"
}
}
}Response
201Successfully created device.
Headers
Content-Type: application/json
Location: https://localhost:3000/api/v1/devices/6Body
{
"data": {
"image": {
"href": "Indeterminate"
},
"firmware": {
"href": "Indeterminate"
},
"platform": "RF200",
"upgrading": false,
"addr": "ccddee",
"id": 6,
"href": "https://localhost:3000/api/v1/devices/6",
"description": "Device1",
"deviceType": "Deck1"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"addr": {
"type": "string",
"description": "Address of device"
},
"upgrading": {
"type": "boolean",
"description": "Indicates whether device is upgrading"
},
"description": {
"type": "string",
"description": "Description of device"
},
"id": {
"type": "integer",
"description": "Unique identifier for device"
},
"href": {
"type": "string",
"description": "URI for this device resource"
},
"platform": {
"type": "string",
"description": "Type of platform"
},
"deviceType": {
"type": "string",
"description": "Type of device"
}
}
}
}
}Response
400Can’t create this device because required device properties are missing.
Body
{
"error": {
"message": "The following properties are required: addr, description, deviceType"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}Response
404Couldn’t find a device type with the specified deviceType description.
Body
{
"error": {
"message": "Device type could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}Response
409Some other device with this MAC address already exists.
Body
{
"error": {
"message": "A device with this address already exists"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": {
"image": {
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
},
"firmware": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1",
"requiresUpgrade": false
},
"platform": "RF200",
"upgrading": false,
"addr": "aabbcc",
"id": 2,
"href": "https://localhost:3000/api/v1/devices/2",
"description": "test",
"deviceType": "Deck1"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"image": {
"properties": {
"href": {
"type": "string",
"description": "URI for this image resource"
}
},
"type": "object",
"description": "Software on device"
},
"firmware": {
"properties": {
"href": {
"type": "string",
"description": "URI for this firmware resource"
},
"requiresUpgrade": {
"type": "boolean",
"description": "Indicates whether firmware requires an upgrade"
}
},
"type": "object",
"description": "Firmware on device"
},
"platform": {
"type": "string",
"description": "Hardware platform"
},
"upgrading": {
"type": "boolean",
"description": "Indicates whether device is upgrading"
},
"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]$",
"type": "string",
"description": "Device MAC address"
},
"id": {
"type": "integer",
"description": "Unique identifier for this device"
},
"href": {
"type": "string",
"description": "URI for this device resource"
},
"description": {
"type": "string",
"description": "User defined name for the device"
},
"deviceType": {
"type": "string",
"description": "Device type"
}
}
}
}
}Response
404No device found for this identifier.
Body
{
"error": {
"message": "Device could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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"
}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"description": {
"type": "string",
"description": "Description of the device"
},
"deviceType": {
"type": "string",
"description": "The type of device. This must exist in the database already."
},
"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]$",
"type": "string",
"description": "SNAP MAC address"
}
},
"title": "Update device",
"type": "object",
"description": "A device"
}Response
200Successfully updated device.
Headers
Content-Type: application/jsonBody
{
"data": {
"image": {
"href": "Indeterminate"
},
"firmware": {
"href": "Indeterminate"
},
"platform": "RF200",
"upgrading": false,
"addr": "ccddee",
"id": 6,
"href": "https://localhost:3000/api/v1/devices/6",
"description": "Device1",
"deviceType": "Deck1"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"image": {
"properties": {
"href": {
"type": "string",
"description": "URI for this image resource"
}
},
"type": "object",
"description": "Image of device"
},
"firmware": {
"properties": {
"href": {
"type": "string",
"description": "URI for this firmware resource"
}
},
"type": "object",
"description": "Firmware of device"
},
"platform": {
"type": "string",
"description": "Type of platform"
},
"upgrading": {
"type": "boolean",
"description": "Indicates whether device is upgrading"
},
"addr": {
"type": "string",
"description": "Address of device"
},
"id": {
"type": "integer",
"description": "Unique identifier for device"
},
"href": {
"type": "string",
"description": "URI for this device resource"
},
"description": {
"type": "string",
"description": "Description of device"
},
"deviceType": {
"type": "string",
"description": "Type of device"
}
}
}
}
}Response
400Can’t update this device because required device properties are missing.
Body
{
"error": {
"message": "The following properties are required: addr, description, deviceType"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": [
{
"description": "Device1",
"deviceType": "Deck1",
"addr": "60866a"
},
{
"description": "Device2",
"deviceType": "Deck1",
"addr": "608477"
}
]
}Schema
{
"required": [
"devices"
],
"title": "Add batch of devices",
"description": "Batch of devices",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"devices": {
"items": {
"required": [
"addr",
"description",
"deviceType"
],
"type": "object",
"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]$",
"type": "string",
"description": "SNAP MAC address"
},
"deviceType": {
"minLength": 1,
"type": "string",
"description": "The type of device. This must exist in the database already."
},
"description": {
"minLength": 1,
"type": "string",
"description": "Description of the device"
}
}
},
"type": "array"
}
}
}Response
201Successfully created devices.
Headers
Content-Type: application/json
Location: https://localhost:3000/api/v1/devices/batches/b38baa5f-ce28-41a3-9bdd-4a14934e826cBody
{
"data": {
"href": "https://localhost:3000/api/v1/devices/batches/b38baa5f-ce28-41a3-9bdd-4a14934e826c",
"devices": [
{
"image": {
"href": "Indeterminate"
},
"firmware": {
"href": "Indeterminate"
},
"upgrading": false,
"addr": "60866a",
"id": 6,
"href": "https://localhost:3000/api/v1/devices/6",
"description": "Device1",
"platform": "RF200",
"deviceType": "Deck1"
},
{
"image": {
"href": "Indeterminate"
},
"firmware": {
"href": "Indeterminate"
},
"upgrading": false,
"addr": "608477",
"id": 7,
"href": "https://localhost:3000/api/v1/devices/7",
"description": "Device2",
"platform": "RF200",
"deviceType": "Deck1"
}
]
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this batch of devices"
},
"devices": {
"items": {
"type": "object",
"properties": {
"image": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this image resource"
}
}
},
"firmware": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this firmware resource"
}
}
},
"upgrading": {
"type": "boolean",
"description": "Indicates whether device is upgrading"
},
"addr": {
"type": "string",
"description": "Address of device"
},
"id": {
"type": "integer",
"description": "Unique identifier for device"
},
"href": {
"type": "string",
"description": "URI for this device resource"
},
"description": {
"type": "string",
"description": "Description of device"
},
"platform": {
"type": "string",
"description": "Type of platform"
},
"deviceType": {
"type": "string",
"description": "Type of device"
}
}
},
"type": "array"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}Response
404Couldn’t find a device type with the specified deviceType description.
Body
{
"error": {
"message": "Device type could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}Response
409Some other device with this MAC address already exists.
Body
{
"error": {
"message": "A device with this address already exists"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}DeviceInfo ¶
DeviceInfo api handler ¶
Update Firmware, Image, Platform for list of devicesPOST/api/v1/devices/info
Example URI
POST /api/v1/devices/info
Request
Body
{
"devices": [
"0600a3",
"0833a4",
"0534fe"
]
}Schema
{
"required": [
"devices"
],
"title": "Device information",
"description": "Device information",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"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]$",
"type": "string",
"description": "SNAP MAC address"
},
"type": "array"
}
}
}Response
202Headers
Location: https://localhost:3000/api/v1/tasks/83f4e242-e89d-407b-95e5-a5a603427217Response
404No device found for this identifier.
Body
{
"error": {
"message": "Device could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": [
{
"href": "https://localhost:3000/api/v1/deviceTypes/",
"id": 1,
"description": "Some Device Type"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this device type resource"
},
"id": {
"type": "integer",
"description": "Unique identifier for this device type"
},
"description": {
"type": "string",
"description": "Name of device type"
}
}
},
"type": "array"
}
}
}Create device typePOST/api/v1/deviceTypes
Example URI
POST /api/v1/deviceTypes
Request
Body
{
"description": "Some Device Type"
}Schema
{
"required": [
"description"
],
"title": "Add device type",
"description": "A device type",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"description": {
"minLength": 1,
"type": "string",
"description": "A unique device type"
}
}
}Response
201Successfully created device type.
Headers
Content-Type: application/json
Location: https://localhost:3000/api/v1/deviceTypes/1Body
{
"data": {
"href": "https://localhost:3000/api/v1/deviceTypes/1",
"id": 1,
"description": "Some Device Type"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this device type resource"
},
"id": {
"type": "integer",
"description": "Unique identifier for this device type"
},
"description": {
"type": "string",
"description": "Name of device type"
}
}
}
}
}Response
409A device type with this description already exists.
Body
{
"error": {
"message": "A device type with this description already exists"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": [
{
"href": "https://localhost:3000/api/v1/deviceTypes/1",
"id": 1,
"description": "Some Device Type"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this device type resource"
},
"id": {
"type": "integer",
"description": "Unique identifier for this device type"
},
"description": {
"type": "string",
"description": "Name of device type"
}
}
},
"type": "array"
}
}
}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
{
"required": [
"description"
],
"title": "Update device type",
"description": "A device type",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"description": {
"minLength": 1,
"type": "string",
"description": "Type of device"
}
}
}Response
200Successfully updated device type.
Headers
Content-Type: application/jsonBody
{
"data": {
"href": "https://localhost:3000/api/v1/deviceTypes/1",
"id": 1,
"description": "Some Device Type"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this device type resource"
},
"id": {
"type": "integer",
"description": "Unique identifier for this device type"
},
"description": {
"type": "string",
"description": "Name of device type"
}
}
}
}
}Response
404No device type found for this identifier.
Body
{
"error": {
"message": "Device type could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}Response
409Some other device type with this description already exists.
Body
{
"error": {
"message": "A device type with this description already exists"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": [
{
"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
{
"type": "object",
"properties": {
"data": {
"items": {
"properties": {
"href": {
"type": "string",
"description": "URI for this firmware resource"
},
"version": {
"type": "string",
"description": "Firmware version number"
}
},
"type": "object",
"description": "A SNAP firmware release"
},
"type": "array"
}
}
}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": {
"href": "https://localhost:3000/api/v1/firmware/2.7.1",
"version": "2.7.1"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"properties": {
"href": {
"type": "string",
"description": "URI for this firmware resource"
},
"version": {
"type": "string",
"description": "Firmware version number"
}
},
"type": "object",
"description": "A SNAP firmware release"
}
}
}Response
404There is no available firmware corresponding to this firmware version number.
Body
{
"error": {
"message": "Firmware could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": {
"actuation": true,
"customer": "John Smith",
"siteDirector": true,
"types": [
"manage",
"deploy"
],
"siteDoctor": true,
"dataCollector": true,
"expiration": "2020-02-05"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"actuation": {
"type": "boolean",
"description": "True if Actuation is licensed"
},
"customer": {
"type": "string",
"description": "The licensed customer"
},
"siteDirector": {
"type": "boolean",
"description": "True if the Site Director is licensed"
},
"types": {
"items": {
"type": "string",
"description": "License types"
},
"type": "array"
},
"siteDoctor": {
"type": "boolean",
"description": "True if the Site Doctor is licensed"
},
"dataCollector": {
"type": "boolean",
"description": "True if the Data Collector is licensed"
},
"expiration": {
"type": "string",
"description": "The date the license expires"
}
}
}
}
}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": {
"deviceTypes": [
{
"description": "a device type description"
},
{
"description": "another device type description"
}
],
"version": 2,
"images": [
{
"name": "MCastCounter",
"crc": "0xda95",
"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",
"size": 3489,
"id": "46fed882-98da-497f-8400-9c92f4c66bb0"
},
{
"name": "BlinkLED",
"crc": "0xda95",
"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",
"size": 2785,
"id": "12abc882-98da-497f-8400-9c92f4c66bb0"
}
],
"dataCollectors": [
{
"deviceTypes": [
"sensors"
],
"dataRpcName": "acceptData",
"initRpcName": "setReceiverAddress",
"dataCollectorType": "asynchronous",
"name": "dc1"
},
{
"deviceTypes": [
"lights"
],
"queryFunction": "data",
"pollInterval": 60,
"dataCollectorType": "synchronous",
"name": "dc2"
}
],
"actuationEnabled": true
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"deviceTypes": {
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Name of device type"
}
}
},
"type": "array"
},
"version": {
"type": "integer",
"description": "The site configuration schema version"
},
"images": {
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for this SPY image resource"
},
"crc": {
"type": "string",
"description": "Checksum of SPY image content"
},
"file": {
"type": "string",
"description": "SPY image content"
},
"size": {
"type": "integer",
"description": "Image size in bytes"
},
"name": {
"type": "string",
"description": "The script name compiled into the SPY image"
}
}
},
"type": "array"
},
"dataCollectors": {
"items": {
"type": "object",
"properties": {
"queryFunction": {
"type": "string",
"description": "Name of query function (sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"name": {
"type": "string",
"description": "Name of data collector"
},
"dataRpcName": {
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (async only)"
},
"pollInterval": {
"type": "integer",
"description": "Number of seconds between polls (sync only)"
},
"initRpcName": {
"type": "string",
"description": "Name of function implemented by SNAPpy script (async only)"
},
"href": {
"type": "string",
"description": "URI for this data collector resource"
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
},
"type": "array"
},
"actuationEnabled": {
"type": "boolean",
"description": "True if actuation is permitted for the system, false otherwise"
}
}
}
}
}Import site configurationPOST/api/v1/siteConfig
Example URI
POST /api/v1/siteConfig
Request
Body
{}Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"required": [
"deviceTypes",
"dataCollectors",
"images",
"actuationEnabled"
],
"type": "object",
"properties": {
"deviceTypes": {
"description": {
"type": "array",
"description": "Device types"
}
},
"version": {
"type": "integer",
"description": "The site configuration schema version"
},
"images": {
"description": {
"type": "array",
"description": "Images"
}
},
"dataCollectors": {
"description": {
"type": "array",
"description": "Data collectors"
}
},
"actuationEnabled": {
"type": "boolean",
"description": "True if actuation is permitted for the system, false otherwise"
}
}
}Response
201The site configuration was successfully imported.
Body
{
"deviceTypes": [
{
"description": "a device type description"
},
{
"description": "another device type description"
}
],
"version": 2,
"images": [
{
"name": "MCastCounter",
"crc": "0xda95",
"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",
"size": 3489,
"id": "46fed882-98da-497f-8400-9c92f4c66bb0"
},
{
"name": "BlinkLED",
"crc": "0xda95",
"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",
"size": 2785,
"id": "12abc882-98da-497f-8400-9c92f4c66bb0"
}
],
"dataCollectors": [
{
"deviceTypes": [
"sensors"
],
"dataRpcName": "acceptData",
"initRpcName": "setReceiverAddress",
"dataCollectorType": "asynchronous",
"name": "dc1"
},
{
"deviceTypes": [
"lights"
],
"queryFunction": "data",
"pollInterval": 60,
"dataCollectorType": "synchronous",
"name": "dc2"
}
],
"actuationEnabled": true
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"deviceTypes": {
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Name of device type"
}
}
},
"type": "array"
},
"dataCollectors": {
"items": {
"type": "object",
"properties": {
"queryFunction": {
"type": "string",
"description": "Name of query function (sync only)"
},
"deviceTypes": {
"items": {
"type": "string",
"description": "Description of device type"
},
"type": "array"
},
"name": {
"type": "string",
"description": "Name of data collector"
},
"dataRpcName": {
"type": "string",
"description": "Name of the RPC that the receiver will listen on for new data (async only)"
},
"pollInterval": {
"type": "integer",
"description": "Number of seconds between polls (sync only)"
},
"initRpcName": {
"type": "string",
"description": "Name of function implemented by SNAPpy script (async only)"
},
"href": {
"type": "string",
"description": "URI for this data collector resource"
},
"dataCollectorType": {
"type": "string",
"description": "Data collector type, one of 'synchronous' or 'asynchronous'"
}
}
},
"type": "array"
},
"images": {
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for this SPY image resource"
},
"href": {
"type": "string",
"description": "URI for this SPY image resource"
},
"crc": {
"type": "string",
"description": "Checksum of SPY image content"
},
"size": {
"type": "integer",
"description": "Image size in bytes"
},
"name": {
"type": "string",
"description": "The script name compiled into the SPY image"
}
}
},
"type": "array"
},
"actuationEnabled": {
"type": "boolean",
"description": "True if actuation is permitted for the system, false otherwise"
}
}
}
}
}Response
400Site configuration could not be imported with these attributes.
Body
{
"error": {
"message": "Site configuration could not be imported with these attributes"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": [
{
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"crc": "0xda95",
"size": 3489,
"name": "McastCounter"
},
{
"id": "f97fdf18-fede-4d58-96d4-eb3f36b4b872",
"href": "https://localhost:3000/api/v1/images/f97fdf18-fede-4d58-96d4-eb3f36b4b872",
"crc": "0x16f1",
"size": 690,
"name": "blink"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this SPY image resource"
},
"crc": {
"type": "string",
"description": "Checksum of SPY image content"
},
"name": {
"type": "string",
"description": "The script name compiled into the SPY image"
},
"size": {
"type": "integer",
"description": "Image size in bytes"
},
"id": {
"type": "string",
"description": "Unique identifier for this SPY image resource"
}
}
},
"type": "array"
}
}
}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
{
"required": [
"content"
],
"title": "Upload SPY image",
"description": "A SPY file image",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"content": {
"media": {
"binaryEncoding": "base64",
"type": "octet-stream"
},
"type": "string",
"description": "Base64-encoded SPY image contents"
}
}
}Response
201Successfully created image.
Headers
Location: https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915dBody
{
"data": {
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"crc": "0xda95",
"size": 3489,
"name": "McastCounter"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for this SPY image resource"
},
"href": {
"type": "string",
"description": "URI for this SPY image resource"
},
"crc": {
"type": "string",
"description": "Checksum of SPY image content"
},
"size": {
"type": "integer",
"description": "Image size in bytes"
},
"name": {
"type": "string",
"description": "The script name compiled into the SPY image"
}
}
}
}
}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": {
"id": "6f992502-33f0-47d4-a01e-973593e1915d",
"href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
"crc": "0xda95",
"size": 3489,
"name": "McastCounter"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this SPY image resource"
},
"crc": {
"type": "string",
"description": "Checksum of SPY image content"
},
"name": {
"type": "string",
"description": "The script name compiled into the SPY image"
},
"size": {
"type": "integer",
"description": "Image size in bytes"
},
"id": {
"type": "string",
"description": "Unique identifier for this SPY image resource"
}
}
},
"type": "array"
}
}
}Response
404No SPY image found for this identifier.
Body
{
"error": {
"message": "Image could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": [
{
"partName": "RF200PF1",
"href": "https://localhost:3000/api/v1/moduleTypes/RF200PF1"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"partName": {
"type": "string",
"description": "Synapse RF Module Type Part Name"
},
"href": {
"type": "string",
"description": "URI for this Synapse RF Module Type"
}
}
},
"type": "array"
}
}
}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": [
{
"href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
"id": "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"
]
}
]
},
{
"href": "https://localhost:3000/api/v1/networkConfigurations/c5fe2546-78f0-09f8-b57b-968745b2789e",
"id": "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
{
"type": "object",
"properties": {
"data": {
"items": {
"description": "A network configuration resource",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this network configuration resource"
},
"id": {
"type": "string",
"description": "Unique identifier for this network configuration resource"
},
"deviceGroupConfigurations": {
"items": {
"description": "Associates a configuration with a group of devices",
"type": "object",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"type": "object",
"properties": {
"image": {
"description": "A SPY image",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
},
"firmware": {
"description": "A SNAP firmware release",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
}
}
},
"devices": {
"uniqueItems": true,
"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]$",
"type": "string",
"description": "SNAP MAC address"
},
"type": "array",
"description": "A group of devices"
}
}
},
"type": "array"
}
}
},
"type": "array"
}
}
}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
{
"required": [
"deviceGroupConfigurations"
],
"title": "Add network configuration",
"description": "A network configuration resource",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"description": "Associates a configuration with a group of devices",
"type": "object",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"type": "object",
"properties": {
"image": {
"description": "A SPY image",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
},
"firmware": {
"description": "A SNAP firmware release",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
}
}
},
"devices": {
"uniqueItems": true,
"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]$",
"type": "string",
"description": "SNAP MAC address"
},
"type": "array",
"description": "A group of devices"
}
}
},
"type": "array"
}
}
}Response
201Successfully created network configuration.
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",
"id": "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
{
"type": "object",
"properties": {
"data": {
"required": [
"deviceGroupConfigurations"
],
"description": "A network configuration resource",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this network configuration resource"
},
"id": {
"type": "string",
"description": "Unique identifier for this network configuration resource"
},
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"description": "Associates a configuration with a group of devices",
"type": "object",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"type": "object",
"properties": {
"image": {
"description": "A SPY image",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
},
"firmware": {
"description": "A SNAP firmware release",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
}
}
},
"devices": {
"uniqueItems": true,
"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]$",
"type": "string",
"description": "SNAP MAC address"
},
"type": "array",
"description": "A group of devices"
}
}
},
"type": "array"
}
}
}
}
}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": {
"href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
"id": "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
{
"type": "object",
"properties": {
"data": {
"required": [
"deviceGroupConfigurations"
],
"description": "A network configuration resource",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this network configuration resource"
},
"id": {
"type": "string",
"description": "Unique identifier for this network configuration resource"
},
"deviceGroupConfigurations": {
"items": {
"required": [
"devices"
],
"description": "Associates a configuration with a group of devices",
"type": "object",
"properties": {
"configuration": {
"description": "A configuration that can be applied to one or more devices",
"type": "object",
"properties": {
"image": {
"description": "A SPY image",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
},
"firmware": {
"description": "A SNAP firmware release",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "Location"
}
}
}
}
},
"devices": {
"uniqueItems": true,
"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]$",
"type": "string",
"description": "SNAP MAC address"
},
"type": "array",
"description": "A group of devices"
}
}
},
"type": "array"
}
}
}
}
}Response
404No network configuration resource found for this identifier.
Body
{
"error": {
"message": "Network configuration resource could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"required": [
"href"
],
"title": "Apply a network configuration update",
"description": "A network configuration location",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "The location of a network configuration"
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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": {
"href": "https://localhost:3000/api/v1/networkConfigurationUpdates/9496aed3-1614-4207-8883-2c807958d940",
"firmware_results": [
{
"address": "60866a",
"result": "failure"
},
{
"address": "608477",
"result": "success"
}
],
"image_results": [
{
"address": "60866a",
"result": "success"
},
{
"address": "608477",
"result": "success"
}
],
"id": "9496aed3-1614-4207-8883-2c807958d940"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this network configuration update results resource"
},
"firmware_results": {
"items": {
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "MAC address for the device described in this result"
},
"result": {
"type": "string",
"description": "Outcome of the attempted update, either success or failure"
}
}
},
"type": "array"
},
"image_results": {
"items": {
"type": "object",
"properties": {
"address": {
"type": "string",
"description": "MAC address for the device described in this result"
},
"result": {
"type": "string",
"description": "Outcome of the attempted update, either success or failure"
}
}
},
"type": "array"
},
"id": {
"type": "string",
"description": "Unique identifier for this results set"
}
}
}
}
}Response
404No such results.
Body
{
"error": {
"message": "Network configuration update results could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI of this task resource"
},
"id": {
"type": "string",
"description": "Unique identifier for this task"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"tcpAccessEnabled": {
"type": "boolean",
"description": "Indicates whether TCP access is enabled"
}
}
}
}
}Enable TCP accessPOST/api/v1/tcpAccess
Example URI
POST /api/v1/tcpAccess
Request
Body
{
"password": "Synapse$0123",
"username": "snap"
}Schema
{
"required": [
"username",
"password"
],
"title": "Add device type",
"description": "A device type",
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"password": {
"minLength": 1,
"type": "string",
"description": "Password for the TCP connection"
},
"username": {
"minLength": 1,
"type": "string",
"description": "Username for the TCP connection"
}
}
}Response
201Successfully opened TCP connection
Response
409TCP access has already been enabled.
Body
{
"error": {
"message": "TCP access has already been enabled"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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",
"gateways": [
"608509"
],
"createdAt": "2016-07-27T13:57:43.361554Z",
"links": [
{
"linkQuality": 71,
"start": "608509",
"end": "5ecad4"
},
{
"linkQuality": 68,
"start": "5ecad4",
"end": "608509"
}
],
"id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c"
}
]
}Schema
{
"type": "object",
"properties": {
"data": {
"items": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this topology resource"
},
"gateways": {
"items": {
"type": "string",
"description": "Gateway MAC address"
},
"type": "array"
},
"createdAt": {
"type": "string",
"description": "Topology creation date (ISO8601 format)"
},
"links": {
"items": {
"type": "object",
"properties": {
"linkQuality": {
"type": "integer",
"description": "Link quality for this link (-dBm)"
},
"start": {
"type": "string",
"description": "Start address for this link"
},
"end": {
"type": "string",
"description": "End address for this link"
}
}
},
"type": "array"
},
"id": {
"type": "string",
"description": "Unique identifier for this topology resource"
}
}
},
"type": "array"
}
}
}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",
"gateways": [
"608509"
],
"createdAt": "2016-07-27T13:57:43.361554Z",
"links": [
{
"linkQuality": 71,
"start": "608509",
"end": "5ecad4"
},
{
"linkQuality": 68,
"start": "5ecad4",
"end": "608509"
}
],
"id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c"
}
}Schema
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "URI for this topology resource"
},
"gateways": {
"items": {
"type": "string",
"description": "Gateway MAC address"
},
"type": "array"
},
"createdAt": {
"type": "string",
"description": "Topology creation date (ISO8601 format)"
},
"links": {
"items": {
"type": "object",
"properties": {
"linkQuality": {
"type": "integer",
"description": "Link quality for this link (-dBm)"
},
"start": {
"type": "string",
"description": "Start address for this link"
},
"end": {
"type": "string",
"description": "End address for this link"
}
}
},
"type": "array"
},
"id": {
"type": "string",
"description": "Unique identifier for this topology resource"
}
}
}
}
}Response
404No device found for this identifier.
Body
{
"error": {
"message": "Topology could not be found"
}
}Schema
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
}
}
}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
{
"type": "object",
"properties": {
"data": {
"type": "boolean",
"description": "Indicates whether topology generation is in progress"
}
}
}