Back to top

SNAP Thing Services API

SNAP Thing Services API Version 1.0.2

Account

Handles requests for the /changePassword resource path

Update password for currently authenticated user
POST/api/v1/changePassword

Password complexity rules are enforced when changing the user’s password; the new password must be at least 8 characters long and include a combination of lower and uppercase letters, numbers, and symbols.

Example URI

POST /api/v1/changePassword
Request
HideShow
Body
{
  "old": "yourOldPassword",
  "new": "yourNewPassword1#"
}
Schema
{
  "type": "object",
  "properties": {
    "old": {
      "description": "Old password",
      "type": "string"
    },
    "new": {
      "pattern": "^(?=.*[0-9])(?=.*[!@#$%^&*_\\-])(?=.*?[a-z])(?=.*?[A-Z])[a-zA-Z0-9!@#$%^&*_\\-]{8,}$",
      "description": "New password",
      "pattern_description": "Password must be at least 8 characters and include a combination of lower and uppercase letters, numbers, and symbols.",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A device",
  "title": "Update device",
  "required": [
    "old",
    "new"
  ]
}
Response  200
HideShow
Body
{
  "data": "Successfully changed password"
}
Schema
{
  "properties": {
    "data": {
      "type": "string"
    }
  },
  "type": "object"
}
Response  400
HideShow

The password could not be changed for any number of reasons (e.g. the old password was incorrect, or the new password does not meet the complexity requirements). The message property of the response should indicate the reason for the failure.

Body
{
  "error": {
    "message": {
      "new": "Password must be at least 8 characters and include a combination of lower and uppercase letters, numbers, and symbols."
    }
  }
}
Schema
{
  "properties": {
    "error": {
      "message": {
        "type": "string"
      },
      "type": "object"
    }
  },
  "type": "object"
}

Administration

Backup

Backup database
GET/api/v1/backup

Create a backup of the current synapse-network-service database

Example URI

GET /api/v1/backup
Response  200
HideShow
Body
"Backup file: synapse-network-service.sqlite"
Response  400
HideShow

The 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 settings
GET/api/v1/network

Example URI

GET /api/v1/network
Response  200
HideShow
Body
{
  "data": {
    "configured_settings": {
      "networkId": "0x3ab3",
      "featureBits": "0x001f",
      "channel": 10,
      "encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
      "encryptionType": "AES-128"
    },
    "bridge_addr": "012345",
    "actual_settings": {
      "networkId": "0x3ab3",
      "featureBits": "0x001f",
      "channel": 10,
      "encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
      "encryptionType": "AES-128"
    }
  }
}
Schema
{
  "properties": {
    "apiVersion": {
      "type": "string"
    },
    "data": {
      "properties": {
        "configured_settings": {
          "description": "Configured network settings",
          "type": "object",
          "properties": {
            "networkId": {
              "description": "The network identifier (ex: '0x1c2c')",
              "type": "string"
            },
            "featureBits": {
              "description": "The hardware settings (ex: '0x001f')",
              "type": "string"
            },
            "channel": {
              "description": "The RF channel",
              "type": "integer"
            },
            "encryptionKey": {
              "description": "The Base64 encoded encryption key",
              "type": "string",
              "media": {
                "binaryEncoding": "base64",
                "type": "octet-stream"
              }
            },
            "encryptionType": {
              "enum": [
                "None",
                "AES-128",
                "Basic"
              ],
              "description": "The type of encryption used to communicate"
            }
          }
        },
        "bridge_addr": {
          "description": "Device MAC Address",
          "type": "string"
        },
        "actual_settings": {
          "description": "Actual bridge node network settings",
          "type": "object",
          "properties": {
            "networkId": {
              "description": "The network identifier (ex: '0x1c2c')",
              "type": "string"
            },
            "featureBits": {
              "description": "The hardware settings (ex: '0x001f')",
              "type": "string"
            },
            "channel": {
              "description": "The RF channel",
              "type": "integer"
            },
            "encryptionKey": {
              "description": "The Base64 encoded encryption key",
              "type": "string",
              "media": {
                "binaryEncoding": "base64",
                "type": "octet-stream"
              }
            },
            "encryptionType": {
              "enum": [
                "None",
                "AES-128",
                "Basic"
              ],
              "description": "The type of encryption used to communicate"
            }
          }
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  400
HideShow

Could not get network settings.

Body
{
  "apiVersion": "v1",
  "error": {
    "message": "Could not get network settings",
    "code": 400
  }
}
Schema
{
  "properties": {
    "apiVersion": {
      "type": "string"
    },
    "error": {
      "properties": {
        "message": {
          "type": "string"
        },
        "code": {
          "description": "HTTP response status",
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Update the current network settings
PUT/api/v1/network

Example URI

PUT /api/v1/network
Request
HideShow
Body
{
  "networkId": "0x3ab3",
  "featureBits": "0x001f",
  "channel": 10,
  "encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
  "encryptionType": "AES-128"
}
Schema
{
  "type": "object",
  "properties": {
    "networkId": {
      "description": "The network identifier (ex: '0x1c2c')",
      "type": "string"
    },
    "featureBits": {
      "description": "The hardware settings (ex: '0x001f')",
      "type": "string"
    },
    "channel": {
      "description": "The RF channel",
      "type": "integer"
    },
    "encryptionKey": {
      "description": "The Base64 encoded encryption key",
      "type": "string",
      "media": {
        "binaryEncoding": "base64",
        "type": "octet-stream"
      }
    },
    "encryptionType": {
      "enum": [
        "None",
        "AES-128",
        "Basic"
      ],
      "description": "The type of encryption used to communicate"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A group of network settings",
  "title": "Update network settings",
  "required": [
    "channel",
    "networkId",
    "featureBits",
    "encryptionType",
    "encryptionKey"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "apiVersion": "v1",
  "data": {
    "networkId": "0x3ab3",
    "featureBits": "0x001f",
    "channel": 10,
    "encryptionKey": "YWFhYWJiYmJjY2NjZGRkZA==",
    "encryptionType": "AES-128"
  }
}
Schema
{
  "properties": {
    "apiVersion": {
      "type": "string"
    },
    "data": {
      "properties": {
        "networkId": {
          "description": "The network identifier (ex: '0x1c2c')",
          "type": "string"
        },
        "featureBits": {
          "description": "The hardware settings (ex: '0x001f')",
          "type": "integer"
        },
        "channel": {
          "description": "The RF channel",
          "type": "integer"
        },
        "encryptionKey": {
          "description": "The Base64 encoded encryption key",
          "type": "string",
          "media": {
            "binaryEncoding": "base64",
            "type": "octet-stream"
          }
        },
        "encryptionType": {
          "enum": [
            "None",
            "AES-128",
            "Basic"
          ],
          "description": "The type of encryption used to communicate"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  400
HideShow

Could not update network settings.

Body
{
  "apiVersion": "v1",
  "error": {
    "message": "Could not update network settings",
    "code": 400
  }
}
Schema
{
  "properties": {
    "apiVersion": {
      "type": "string"
    },
    "error": {
      "properties": {
        "message": {
          "type": "string"
        },
        "code": {
          "description": "HTTP response status",
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Data Collector

Root of DC routes

Get the list of data collectors
GET/api/v1/dc

Example URI

GET /api/v1/dc
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "name": "dc1",
      "deviceTypes": [
        "sensors"
      ],
      "href": "https://localhost:3000/api/v1/dc/dc1",
      "queryFunction": "data",
      "id": 1,
      "pollInterval": 60
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "name": {
            "description": "Name of data collector",
            "type": "string"
          },
          "deviceTypes": {
            "items": {
              "description": "Description of device type",
              "type": "string"
            },
            "type": "array"
          },
          "href": {
            "description": "URI for this data collector resource",
            "type": "string"
          },
          "queryFunction": {
            "description": "Name of query function",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this data collector",
            "type": "integer"
          },
          "pollInterval": {
            "description": "Number of seconds between polls",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

Create a data collector
POST/api/v1/dc

Example URI

POST /api/v1/dc
Request
HideShow
Body
{
  "deviceTypes": [
    "sensors"
  ],
  "name": "dc1",
  "pollInterval": 60,
  "queryFunction": "data"
}
Schema
{
  "description": "A data collector",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Add data collector",
  "type": "object",
  "properties": {
    "properties": {
      "deviceTypes": {
        "items": {
          "description": "Description of device type",
          "type": "string"
        },
        "type": "array"
      },
      "name": {
        "description": "Name of data collector",
        "type": "string"
      },
      "pollInterval": {
        "description": "Number of seconds between polls",
        "type": "integer"
      },
      "queryFunction": {
        "description": "Name of query function",
        "type": "string"
      }
    },
    "type": "object"
  }
}
Response  201
HideShow
Body
{
  "data": {
    "name": "dc1",
    "deviceTypes": [
      "sensors"
    ],
    "href": "https://localhost:3000/api/v1/dc/dc1",
    "queryFunction": "data",
    "id": 1,
    "pollInterval": 60
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "name": {
          "description": "Name of data collector",
          "type": "string"
        },
        "deviceTypes": {
          "items": {
            "description": "Description of device type",
            "type": "string"
          },
          "type": "array"
        },
        "href": {
          "description": "URI for this data collector resource",
          "type": "string"
        },
        "queryFunction": {
          "description": "Name of query function",
          "type": "string"
        },
        "id": {
          "description": "Unique identifier for this data collector",
          "type": "integer"
        },
        "pollInterval": {
          "description": "Number of seconds between polls",
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  409
HideShow

A 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"
}

Root of single DC routes

Delete a data collector
DELETE/api/v1/dc/{name}

Example URI

DELETE /api/v1/dc/dc1
URI Parameters
HideShow
name
string (required) Example: dc1

Name of a data collector

Response  204
HideShow

The data collector was successfully deleted.

Response  404
HideShow

No 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"
}

Single DC Config

Get a single data collector's configuration
GET/api/v1/dc/{name}/config

Example URI

GET /api/v1/dc/dc1/config
URI Parameters
HideShow
name
string (required) Example: dc1

Name of a data collector

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "name": "dc1",
    "deviceTypes": [
      "sensors"
    ],
    "href": "https://localhost:3000/api/v1/dc/dc1",
    "queryFunction": "data",
    "id": 1,
    "pollInterval": 60
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "name": {
          "description": "Name of data collector",
          "type": "string"
        },
        "deviceTypes": {
          "items": {
            "description": "Description of device type",
            "type": "string"
          },
          "type": "array"
        },
        "href": {
          "description": "URI for this data collector resource",
          "type": "string"
        },
        "queryFunction": {
          "description": "Name of query function",
          "type": "string"
        },
        "id": {
          "description": "Unique identifier for this data collector",
          "type": "integer"
        },
        "pollInterval": {
          "description": "Number of seconds between polls",
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Update a single data collector
PUT/api/v1/dc/{name}/config

Example URI

PUT /api/v1/dc/dc1/config
URI Parameters
HideShow
name
string (required) Example: dc1

Name of a data collector

Request
HideShow
Body
{
  "deviceTypes": [
    "sensors"
  ],
  "name": "dc1",
  "pollInterval": 60,
  "queryFunction": "data"
}
Schema
{
  "description": "A data collector",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Update a data collector",
  "type": "object",
  "properties": {
    "properties": {
      "deviceTypes": {
        "items": {
          "description": "Description of device type",
          "type": "string"
        },
        "type": "array"
      },
      "name": {
        "description": "Name of data collector",
        "type": "string"
      },
      "pollInterval": {
        "description": "Number of seconds between polls",
        "type": "integer"
      },
      "queryFunction": {
        "description": "Name of query function",
        "type": "string"
      }
    },
    "type": "object"
  }
}
Response  200
HideShow
Body
{
  "data": {
    "name": "dc1",
    "deviceTypes": [
      "sensors"
    ],
    "href": "https://localhost:3000/api/v1/dc/dc1",
    "queryFunction": "data",
    "id": 1,
    "pollInterval": 60
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "name": {
          "description": "Name of data collector",
          "type": "string"
        },
        "deviceTypes": {
          "items": {
            "description": "Description of device type",
            "type": "string"
          },
          "type": "array"
        },
        "href": {
          "description": "URI for this data collector resource",
          "type": "string"
        },
        "queryFunction": {
          "description": "Name of query function",
          "type": "string"
        },
        "id": {
          "description": "Unique identifier for this data collector",
          "type": "integer"
        },
        "pollInterval": {
          "description": "Number of seconds between polls",
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Devices

Device Collection

Get list of devices
GET/api/v1/devices{?expand}{&type}

Example URI

GET /api/v1/devices?expand=firmware,image&type=Sensor
URI Parameters
HideShow
expand
string (optional) Example: firmware,image

Expand HREF properties to full objects (e.g. ?expand=firmware,image)

type
string (optional) Example: Sensor

Limit result to devices with this device type

Response  200
HideShow
Body
{
  "data": [
    {
      "upgrading": false,
      "addr": "aabbcc",
      "firmware": {
        "href": "https://localhost:3000/api/v1/firmware/2.7.1"
      },
      "platform": "RF200",
      "description": "test",
      "href": "https://localhost:3000/api/v1/devices/2",
      "deviceType": "Deck1",
      "id": 2,
      "image": {
        "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
      }
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "upgrading": {
            "description": "Indicates whether device is upgrading",
            "type": "boolean"
          },
          "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"
          },
          "firmware": {
            "description": "Firmware on device",
            "type": "object",
            "properties": {
              "href": {
                "description": "URI for this firmware resource",
                "type": "string"
              }
            }
          },
          "platform": {
            "description": "Hardware platform",
            "type": "string"
          },
          "description": {
            "description": "User defined name for the device",
            "type": "string"
          },
          "href": {
            "description": "URI for this device resource",
            "type": "string"
          },
          "deviceType": {
            "description": "Device type",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this device",
            "type": "integer"
          },
          "image": {
            "description": "Software on device",
            "type": "object",
            "properties": {
              "href": {
                "description": "URI for this image resource",
                "type": "string"
              }
            }
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

Create a device
POST/api/v1/devices

Clients should use this endpoint to create a single new Device resource. If you need to create a lot of new devices in a bulk operation, please refer to the “Device Batches” section.

Example URI

POST /api/v1/devices
Request
HideShow
Body
{
  "deviceType": "Deck1",
  "description": "Device1",
  "addr": "ccddee",
  "platform": "RF200"
}
Schema
{
  "type": "object",
  "properties": {
    "deviceType": {
      "description": "The type of device. This must exist in the database already.",
      "type": "string"
    },
    "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"
    },
    "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#",
  "description": "A device",
  "title": "Add device",
  "required": [
    "addr",
    "description",
    "platform",
    "deviceType"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: https://localhost:3000/api/v1/devices/6
Body
{
  "data": {
    "upgrading": false,
    "addr": "ccddee",
    "firmware": {
      "href": "Unknown"
    },
    "platform": "RF200",
    "description": "Device1",
    "href": "https://localhost:3000/api/v1/devices/6",
    "deviceType": "Deck1",
    "id": 6,
    "image": {
      "href": "Unknown"
    }
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "upgrading": {
          "description": "Indicates whether device is upgrading",
          "type": "boolean"
        },
        "addr": {
          "description": "Address of device",
          "type": "string"
        },
        "platform": {
          "description": "Type of platform",
          "type": "string"
        },
        "description": {
          "description": "Description of device",
          "type": "string"
        },
        "href": {
          "description": "URI for this device resource",
          "type": "string"
        },
        "deviceType": {
          "description": "Type of device",
          "type": "string"
        },
        "id": {
          "description": "Unique identifier for device",
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  400
HideShow

Can’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  404
HideShow

Couldn’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  409
HideShow

Some 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 device
GET/api/v1/devices/{deviceId}

Example URI

GET /api/v1/devices/2
URI Parameters
HideShow
deviceId
integer (required) Example: 2

Unique identifier for a device

Response  200
HideShow
Body
{
  "data": {
    "upgrading": false,
    "addr": "aabbcc",
    "firmware": {
      "href": "https://localhost:3000/api/v1/firmware/2.7.1"
    },
    "platform": "RF200",
    "description": "test",
    "href": "https://localhost:3000/api/v1/devices/2",
    "deviceType": "Deck1",
    "id": 2,
    "image": {
      "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
    }
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "upgrading": {
          "description": "Indicates whether device is upgrading",
          "type": "boolean"
        },
        "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"
        },
        "firmware": {
          "description": "Firmware on device",
          "type": "object",
          "properties": {
            "href": {
              "description": "URI for this firmware resource",
              "type": "string"
            }
          }
        },
        "platform": {
          "description": "Hardware platform",
          "type": "string"
        },
        "description": {
          "description": "User defined name for the device",
          "type": "string"
        },
        "href": {
          "description": "URI for this device resource",
          "type": "string"
        },
        "deviceType": {
          "description": "Device type",
          "type": "string"
        },
        "id": {
          "description": "Unique identifier for this device",
          "type": "integer"
        },
        "image": {
          "description": "Software on device",
          "type": "object",
          "properties": {
            "href": {
              "description": "URI for this image resource",
              "type": "string"
            }
          }
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  404
HideShow

No 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 Device
PUT/api/v1/devices/{deviceId}

Example URI

PUT /api/v1/devices/2
URI Parameters
HideShow
deviceId
integer (required) Example: 2

Unique identifier for a device

Request
HideShow
Body
{
  "deviceType": "Deck1",
  "description": "Device1",
  "addr": "ccddee",
  "platform": "RF200"
}
Schema
{
  "description": "A device",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "Update device",
  "type": "object",
  "properties": {
    "deviceType": {
      "description": "The type of device. This must exist in the database already.",
      "type": "string"
    },
    "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"
    },
    "description": {
      "description": "Description of the device",
      "type": "string"
    },
    "platform": {
      "description": "The device platform (ex: RF200)",
      "type": "string"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "upgrading": false,
    "addr": "ccddee",
    "firmware": {
      "href": "Unknown"
    },
    "platform": "RF200",
    "description": "Device1",
    "href": "https://localhost:3000/api/v1/devices/6",
    "deviceType": "Deck1",
    "id": 6,
    "image": {
      "href": "Unknown"
    }
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "upgrading": {
          "description": "Indicates whether device is upgrading",
          "type": "boolean"
        },
        "addr": {
          "description": "Address of device",
          "type": "string"
        },
        "firmware": {
          "description": "Firmware of device",
          "type": "object",
          "properties": {
            "href": {
              "description": "URI for this firmware resource",
              "type": "string"
            }
          }
        },
        "platform": {
          "description": "Type of platform",
          "type": "string"
        },
        "description": {
          "description": "Description of device",
          "type": "string"
        },
        "href": {
          "description": "URI for this device resource",
          "type": "string"
        },
        "deviceType": {
          "description": "Type of device",
          "type": "string"
        },
        "id": {
          "description": "Unique identifier for device",
          "type": "integer"
        },
        "image": {
          "description": "Image of device",
          "type": "object",
          "properties": {
            "href": {
              "description": "URI for this image resource",
              "type": "string"
            }
          }
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  400
HideShow

Can’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  404
HideShow

No 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  409
HideShow

Can’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 Device
DELETE/api/v1/devices/{deviceId}

Example URI

DELETE /api/v1/devices/2
URI Parameters
HideShow
deviceId
integer (required) Example: 2

Unique identifier for a device

Response  204
HideShow

The device was successfully deleted

Response  404
HideShow

No 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 Devices
POST/api/v1/devices/batches

Use this endpoint to efficiently create a large number of Device resources.

Example URI

POST /api/v1/devices/batches
Request
HideShow
Body
{
  "devices": [
    {
      "deviceType": "Deck1",
      "description": "Device1",
      "platform": "RF200",
      "addr": "60866a"
    },
    {
      "deviceType": "Deck1",
      "description": "Device2",
      "platform": "RF200",
      "addr": "608477"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "devices": {
      "items": {
        "properties": {
          "deviceType": {
            "minLength": 1,
            "description": "The type of device. This must exist in the database already.",
            "type": "string"
          },
          "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"
          },
          "description": {
            "minLength": 1,
            "description": "Description of the device",
            "type": "string"
          },
          "platform": {
            "minLength": 1,
            "description": "The device platform (ex: RF200)",
            "type": "string"
          }
        },
        "required": [
          "addr",
          "description",
          "platform",
          "deviceType"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Batch of devices",
  "title": "Add batch of devices",
  "required": [
    "devices"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: https://localhost:3000/api/v1/devices/batches/b38baa5f-ce28-41a3-9bdd-4a14934e826c
Body
{
  "data": {
    "devices": [
      {
        "upgrading": false,
        "addr": "60866a",
        "firmware": {
          "href": "Unknown"
        },
        "platform": "RF200",
        "description": "Device1",
        "href": "https://localhost:3000/api/v1/devices/6",
        "deviceType": "Deck1",
        "id": 6,
        "image": {
          "href": "Unknown"
        }
      },
      {
        "upgrading": false,
        "addr": "608477",
        "firmware": {
          "href": "Unknown"
        },
        "platform": "RF200",
        "description": "Device2",
        "href": "https://localhost:3000/api/v1/devices/7",
        "deviceType": "Deck1",
        "id": 7,
        "image": {
          "href": "Unknown"
        }
      }
    ],
    "href": "https://localhost:3000/api/v1/devices/batches/b38baa5f-ce28-41a3-9bdd-4a14934e826c"
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "devices": {
          "items": {
            "properties": {
              "upgrading": {
                "description": "Indicates whether device is upgrading",
                "type": "boolean"
              },
              "addr": {
                "description": "Address of device",
                "type": "string"
              },
              "firmware": {
                "properties": {
                  "href": {
                    "description": "URI for this firmware resource",
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "platform": {
                "description": "Type of platform",
                "type": "string"
              },
              "description": {
                "description": "Description of device",
                "type": "string"
              },
              "href": {
                "description": "URI for this device resource",
                "type": "string"
              },
              "deviceType": {
                "description": "Type of device",
                "type": "string"
              },
              "id": {
                "description": "Unique identifier for device",
                "type": "integer"
              },
              "image": {
                "properties": {
                  "href": {
                    "description": "URI for this image resource",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "href": {
          "description": "URI for this batch of devices",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  400
HideShow

Can’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  404
HideShow

Couldn’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  409
HideShow

Some other device with this MAC address already exists.

Body
{
  "error": {
    "message": "A device with this address already exists"
  }
}
Schema
{
  "properties": {
    "error": {
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Device Types

Device Types Collection

Handles requests for the /deviceTypes resource path.

Get list of device types
GET/api/v1/deviceTypes

Example URI

GET /api/v1/deviceTypes
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": [
    {
      "id": 1,
      "href": "https://localhost:3000/api/v1/deviceTypes/",
      "description": "Some Device Type"
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "id": {
            "description": "Unique identifier for this device type",
            "type": "integer"
          },
          "href": {
            "description": "URI for this device type resource",
            "type": "string"
          },
          "description": {
            "description": "Name of device type",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

Create device type
POST/api/v1/deviceTypes

Example URI

POST /api/v1/deviceTypes
Request
HideShow
Body
{
  "description": "Some Device Type"
}
Schema
{
  "type": "object",
  "properties": {
    "description": {
      "minLength": 1,
      "description": "A unique device type",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A device type",
  "title": "Add device type",
  "required": [
    "description"
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Location: https://localhost:3000/api/v1/deviceTypes/1
Body
{
  "data": {
    "id": 1,
    "href": "https://localhost:3000/api/v1/deviceTypes/1",
    "description": "Some Device Type"
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "id": {
          "description": "Unique identifier for this device type",
          "type": "integer"
        },
        "href": {
          "description": "URI for this device type resource",
          "type": "string"
        },
        "description": {
          "description": "Name of device type",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  409
HideShow

A device type with this description already exists.

Body
{
  "error": {
    "message": "A device type with this description already exists"
  }
}
Schema
{
  "properties": {
    "error": {
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Device Type

Handles requests for the /deviceTypes/{deviceTypeId} resource path.

Get a single device type
GET/api/v1/deviceTypes/{deviceTypeId}

Example URI

GET /api/v1/deviceTypes/1
URI Parameters
HideShow
deviceTypeId
integer (required) Example: 1

Unique identifier for a device type

Response  200
HideShow
Body
{
  "data": [
    {
      "id": 1,
      "href": "https://localhost:3000/api/v1/deviceTypes/1",
      "description": "Some Device Type"
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "id": {
            "description": "Unique identifier for this device type",
            "type": "integer"
          },
          "href": {
            "description": "URI for this device type resource",
            "type": "string"
          },
          "description": {
            "description": "Name of device type",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

Update device type
PUT/api/v1/deviceTypes/{deviceTypeId}

Example URI

PUT /api/v1/deviceTypes/1
URI Parameters
HideShow
deviceTypeId
integer (required) Example: 1

Unique identifier for a device type

Request
HideShow
Body
{
  "description": "Some Device Type"
}
Schema
{
  "type": "object",
  "properties": {
    "description": {
      "minLength": 1,
      "description": "Type of device",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A device type",
  "title": "Update device type",
  "required": [
    "description"
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": 1,
    "href": "https://localhost:3000/api/v1/deviceTypes/1",
    "description": "Some Device Type"
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "id": {
          "description": "Unique identifier for this device type",
          "type": "integer"
        },
        "href": {
          "description": "URI for this device type resource",
          "type": "string"
        },
        "description": {
          "description": "Name of device type",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  404
HideShow

No 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  409
HideShow

Some 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 type
DELETE/api/v1/deviceTypes/{deviceTypeId}

Example URI

DELETE /api/v1/deviceTypes/1
URI Parameters
HideShow
deviceTypeId
integer (required) Example: 1

Unique identifier for a device type

Response  204
HideShow

The device type was successfully deleted.

Response  404
HideShow

No 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 firmware
GET/api/v1/firmware

Example URI

GET /api/v1/firmware
Response  200
HideShow

An array of firmware resources. Note that if no SNAP firmware is available, this will return an empty array.

Headers
Content-Type: application/json
Body
{
  "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",
        "type": "object",
        "properties": {
          "version": {
            "description": "Firmware version number",
            "type": "string"
          },
          "href": {
            "description": "URI for this firmware resource",
            "type": "string"
          }
        }
      },
      "type": "array"
    }
  },
  "type": "object"
}

Firmware

Handles requests for the /firmware/{firmwareVersion} resource path.

Retrieve specifc firmware resource
GET/api/v1/firmware/{firmwareVersion}

Example URI

GET /api/v1/firmware/2.7.1
URI Parameters
HideShow
firmwareVersion
string (required) Example: 2.7.1

Unique identifier for a firmware version

Response  200
HideShow

The firmware resource corresponding to the specified version number.

Body
{
  "data": {
    "version": "2.7.1",
    "href": "https://localhost:3000/api/v1/firmware/2.7.1"
  }
}
Schema
{
  "properties": {
    "data": {
      "description": "A SNAP firmware release",
      "type": "object",
      "properties": {
        "version": {
          "description": "Firmware version number",
          "type": "string"
        },
        "href": {
          "description": "URI for this firmware resource",
          "type": "string"
        }
      }
    }
  },
  "type": "object"
}
Response  404
HideShow

There is no available firmware corresponding to this firmware version number.

Body
{
  "error": {
    "message": "Firmware could not be found"
  }
}
Schema
{
  "properties": {
    "error": {
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

License

License

Handles requests for the /license resource path.

Apply a SNAP Thing Services License
PUT/api/v1/license

The license needs to be Base64-encoded before it can be uploaded to the SNAP Thing Services.

Please contact Synapse Customer Service to receive a license. A license gives you access to:

  • Bulk upgrades

  • Data collection with no node limit

  • Topology with no node limit

Example URI

PUT /api/v1/license
Response  200
HideShow

SNAP Thing Services License successfully applied

Delete the license
DELETE/api/v1/license

Example URI

DELETE /api/v1/license
Response  204
HideShow

The license was successfully deleted

License Capabilities

Handles requests for the /licenseCapabilities resource path.

Get license capabilities
GET/api/v1/licenseCapabilities

Example URI

GET /api/v1/licenseCapabilities
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "customer": "John Smith",
    "siteDirector": true,
    "dataCollector": true,
    "types": [
      "manage",
      "deploy"
    ],
    "expiration": "2020-02-05",
    "siteDoctor": true
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "customer": {
          "description": "The licensed customer",
          "type": "string"
        },
        "siteDirector": {
          "description": "True if the Site Director is licensed",
          "type": "boolean"
        },
        "dataCollector": {
          "description": "True if the Data Collector is licensed",
          "type": "boolean"
        },
        "types": {
          "items": {
            "description": "License types",
            "type": "string"
          },
          "type": "array"
        },
        "expiration": {
          "description": "The date the license expires",
          "type": "string"
        },
        "siteDoctor": {
          "description": "True if the Site Doctor is licensed",
          "type": "boolean"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

SPY Images

SPY Image Collection

Handles requests for the /images resource path.

Get all SPY images
GET/api/v1/images

Example URI

GET /api/v1/images
Response  200
HideShow

An array of SPY file images uploaded to the service. If no SPY images have been uploaded, the response contains an empty array.

Body
{
  "data": [
    {
      "name": "McastCounter",
      "size": 3489,
      "id": "6f992502-33f0-47d4-a01e-973593e1915d",
      "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
      "crc": "0xda95"
    },
    {
      "name": "blink",
      "size": 690,
      "id": "f97fdf18-fede-4d58-96d4-eb3f36b4b872",
      "href": "https://localhost:3000/api/v1/images/f97fdf18-fede-4d58-96d4-eb3f36b4b872",
      "crc": "0x16f1"
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "size": {
            "description": "Image size in bytes",
            "type": "integer"
          },
          "id": {
            "description": "Unique identifier for this SPY image",
            "type": "string"
          },
          "name": {
            "description": "The script name compiled into the SPY image",
            "type": "string"
          },
          "href": {
            "description": "URI for this image resource",
            "type": "string"
          },
          "crc": {
            "description": "CRC",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

Create a new SPY image
POST/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
HideShow
Body
{
  "content": "<Base64-encoded SPY file contents>"
}
Schema
{
  "type": "object",
  "properties": {
    "content": {
      "description": "Base64-encoded SPY image contents",
      "type": "string",
      "media": {
        "binaryEncoding": "base64",
        "type": "octet-stream"
      }
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A SPY file image",
  "title": "Upload SPY image",
  "required": [
    "content"
  ]
}
Response  201
HideShow
Headers
Location: https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d
Body
{
  "data": {
    "name": "McastCounter",
    "size": 3489,
    "id": "6f992502-33f0-47d4-a01e-973593e1915d",
    "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
    "crc": "0xda95"
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "name": {
          "description": "The script name compiled into the SPY image",
          "type": "string"
        },
        "size": {
          "description": "Image size in bytes",
          "type": "integer"
        },
        "id": {
          "description": "Unique identifier for this SPY image",
          "type": "string"
        },
        "href": {
          "description": "URI for this image resource",
          "type": "string"
        },
        "crc": {
          "description": "CRC",
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Delete all SPY images
DELETE/api/v1/images

Example URI

DELETE /api/v1/images
Response  204

SPY Image

Handles requests for the /images/{imageId} resource path.

Get a single SPY image
GET/api/v1/images/{imageId}

Example URI

GET /api/v1/images/1
URI Parameters
HideShow
imageId
integer (required) Example: 1

Unique identifier for a SPY image

Response  200
HideShow
Body
{
  "data": {
    "name": "McastCounter",
    "size": 3489,
    "id": "6f992502-33f0-47d4-a01e-973593e1915d",
    "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d",
    "crc": "0xda95"
  }
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "id": {
            "description": "Unique identifier for this device type",
            "type": "integer"
          },
          "href": {
            "description": "URI for this device type resource",
            "type": "string"
          },
          "description": {
            "description": "Name of device type",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}
Response  404
HideShow

No 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 image
DELETE/api/v1/images/{imageId}

Example URI

DELETE /api/v1/images/1
URI Parameters
HideShow
imageId
integer (required) Example: 1

Unique identifier for a SPY image

Response  204
HideShow

The SPY image was successfully deleted

Response  404
HideShow

No 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 Types
GET/api/v1/moduleTypes

Example URI

GET /api/v1/moduleTypes
Response  200
HideShow

An array of Synapse RF Module Types

Body
{
  "data": [
    {
      "partName": "RF200PF1",
      "href": "https://localhost:3000/api/v1/moduleTypes/RF200PF1"
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "partName": {
            "description": "Synapse RF Module Type Part Name",
            "type": "string"
          },
          "href": {
            "description": "URI for this Synapse RF Module Type",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

Network Configuration

Network Configurations Collection

Get a List of All Network Configurations
GET/api/v1/networkConfigurations

Example URI

GET /api/v1/networkConfigurations
Response  200
HideShow
Body
{
  "data": [
    {
      "deviceGroupConfigurations": [
        {
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
            }
          },
          "devices": [
            "03cd71",
            "04ab44"
          ]
        },
        {
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
            }
          },
          "devices": [
            "00a400",
            "040128"
          ]
        }
      ],
      "id": "7e968754-78f0-09f8-b57b-968745b2789e",
      "href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e"
    },
    {
      "deviceGroupConfigurations": [
        {
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/4d271412-33f0-47d4-a01e-973593e1915d"
            }
          },
          "devices": [
            "082614",
            "7531df"
          ]
        },
        {
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/9e524135-3a66-49c0-9126-98c901cd6ee4"
            }
          },
          "devices": [
            "04abaf",
            "604def"
          ]
        }
      ],
      "id": "c5fe2546-78f0-09f8-b57b-968745b2789e",
      "href": "https://localhost:3000/api/v1/networkConfigurations/c5fe2546-78f0-09f8-b57b-968745b2789e"
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "description": "A network configuration",
        "type": "object",
        "properties": {
          "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": {
                          "description": "Location",
                          "type": "string"
                        }
                      }
                    },
                    "firmware": {
                      "description": "A SNAP firmware release",
                      "type": "object",
                      "properties": {
                        "href": {
                          "description": "Location",
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "devices": {
                  "uniqueItems": true,
                  "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",
                  "type": "array"
                }
              }
            },
            "type": "array"
          },
          "id": {
            "description": "Unique identifier for this network configuration",
            "type": "string"
          },
          "href": {
            "description": "URI for this network configuration resource",
            "type": "string"
          }
        }
      },
      "type": "array"
    }
  },
  "type": "object"
}

Create a Network Configuration
POST/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
HideShow
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
{
  "type": "object",
  "properties": {
    "deviceGroupConfigurations": {
      "items": {
        "description": "Associates a configuration with a group of devices",
        "required": [
          "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": {
                    "description": "Location",
                    "type": "string"
                  }
                }
              },
              "firmware": {
                "description": "A SNAP firmware release",
                "type": "object",
                "properties": {
                  "href": {
                    "description": "Location",
                    "type": "string"
                  }
                }
              }
            }
          },
          "devices": {
            "uniqueItems": true,
            "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",
            "type": "array"
          }
        }
      },
      "type": "array"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A network configuration",
  "title": "Add network configuration",
  "required": [
    "deviceGroupConfigurations"
  ]
}
Response  201
HideShow
Headers
Location: https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e
Body
{
  "data": {
    "deviceGroupConfigurations": [
      {
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
          }
        },
        "devices": [
          "03cd71",
          "04ab44"
        ]
      },
      {
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
          }
        },
        "devices": [
          "00a400",
          "040128"
        ]
      }
    ],
    "id": "7e968754-78f0-09f8-b57b-968745b2789e",
    "href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e"
  }
}
Schema
{
  "properties": {
    "data": {
      "description": "A network configuration",
      "required": [
        "deviceGroupConfigurations"
      ],
      "type": "object",
      "properties": {
        "deviceGroupConfigurations": {
          "items": {
            "description": "Associates a configuration with a group of devices",
            "required": [
              "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": {
                        "description": "Location",
                        "type": "string"
                      }
                    }
                  },
                  "firmware": {
                    "description": "A SNAP firmware release",
                    "type": "object",
                    "properties": {
                      "href": {
                        "description": "Location",
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "devices": {
                "uniqueItems": true,
                "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",
                "type": "array"
              }
            }
          },
          "type": "array"
        },
        "id": {
          "description": "Unique identifier for this network configuration",
          "type": "string"
        },
        "href": {
          "description": "URI for this network configuration resource",
          "type": "string"
        }
      }
    }
  },
  "type": "object"
}

Network Configuration

Get a Network Configuration
GET/api/v1/networkConfigurations/{networkConfigurationId}

Example URI

GET /api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e
URI Parameters
HideShow
networkConfigurationId
string (required) Example: 7e968754-78f0-09f8-b57b-968745b2789e

Unique identifier for a network configuration

Response  200
HideShow
Body
{
  "data": {
    "deviceGroupConfigurations": [
      {
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
          }
        },
        "devices": [
          "03cd71",
          "04ab44"
        ]
      },
      {
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
          }
        },
        "devices": [
          "00a400",
          "040128"
        ]
      }
    ],
    "id": "7e968754-78f0-09f8-b57b-968745b2789e",
    "href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e"
  }
}
Schema
{
  "properties": {
    "data": {
      "description": "A network configuration",
      "required": [
        "deviceGroupConfigurations"
      ],
      "type": "object",
      "properties": {
        "deviceGroupConfigurations": {
          "items": {
            "description": "Associates a configuration with a group of devices",
            "required": [
              "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": {
                        "description": "Location",
                        "type": "string"
                      }
                    }
                  },
                  "firmware": {
                    "description": "A SNAP firmware release",
                    "type": "object",
                    "properties": {
                      "href": {
                        "description": "Location",
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "devices": {
                "uniqueItems": true,
                "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",
                "type": "array"
              }
            }
          },
          "type": "array"
        },
        "id": {
          "description": "Unique identifier for this network configuration",
          "type": "string"
        },
        "href": {
          "description": "URI for this network configuration resource",
          "type": "string"
        }
      }
    }
  },
  "type": "object"
}
Response  404
HideShow

No network configuration found for this identifier.

Body
{
  "error": {
    "message": "Network configuration 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 Update
POST/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
HideShow
Body
{
  "href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e"
}
Schema
{
  "type": "object",
  "properties": {
    "href": {
      "description": "The location of a network configuration",
      "type": "string"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "A network configuration location",
  "title": "Apply a network configuration update",
  "required": [
    "href"
  ]
}
Response  202
HideShow
Headers
Location: https://localhost:3000/api/v1/tasks/8ba8d8bd-edeb-4960-bb05-87c75697bf6d
Response  400
HideShow

A 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  403
HideShow

A network configuration update will not start if the network configuration descriptionidentifies multiple devices but the user’s license restricts them to upgrading only onedevice at a time.

Body
{
  "error": {
    "message": "Your license only permits upgrading one device at a time. Please contact your sales representative to discuss upgrading your license to support upgrading multiple device at the same time."
  }
}
Schema
{
  "properties": {
    "error": {
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  404
HideShow

If 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 update
GET/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
HideShow
networkConfigurationUpdateId
string (required) Example: 7e968754-78f0-09f8-b57b-968745b2789e

Unique identifier for a network configuration update result

Response  200
HideShow
Body
{
  "data": {
    "firmware_results": [
      {
        "result": "failure",
        "address": "60866a"
      },
      {
        "result": "success",
        "address": "608477"
      }
    ],
    "id": "9496aed3-1614-4207-8883-2c807958d940",
    "href": "https://localhost:3000/api/v1/networkConfigurationUpdates/9496aed3-1614-4207-8883-2c807958d940",
    "image_results": [
      {
        "result": "success",
        "address": "60866a"
      },
      {
        "result": "success",
        "address": "608477"
      }
    ]
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "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"
        },
        "id": {
          "description": "Unique identifier for this results set",
          "type": "string"
        },
        "href": {
          "description": "URI for this network configuration update results resource",
          "type": "string"
        },
        "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"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  404
HideShow

No such results

Body
{
  "error": {
    "message": "Network configuration update results could not be found"
  }
}
Schema
{
  "properties": {
    "error": {
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Tasks

Task

Get task status
GET/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
HideShow
taskId
string (required) Example: 7e968754-78f0-09f8-b57b-968745b2789e

Unique identifier for a task

Response  200
HideShow

This 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  303
HideShow

This 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-2c807958d940
Response  404
HideShow

No task found for this identifier.

Body
{
  "error": {
    "message": "Task could not be found"
  }
}
Schema
{
  "properties": {
    "error": {
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Sockets

SockJS Endpoint

Connect SockJS
GET/ws

See http://sockjs.org for details on making a connection.

Example URI

GET /ws
Response  200
HideShow
Body
"Established SockJS Connection"

Websocket Endpoint

Connect Websocket
GET/ws/websocket

Example URI

GET /ws/websocket
Response  200
HideShow
Body
"Established Websocket Connection"

Topologies

SNAP Network Topology Collection

Get all topologies
GET/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  200
HideShow
Body
{
  "data": [
    {
      "links": [
        {
          "end": "5ecad4",
          "linkQuality": 71,
          "start": "608509"
        },
        {
          "end": "608509",
          "linkQuality": 68,
          "start": "5ecad4"
        }
      ],
      "id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
      "createdAt": "2016-07-27T13:57:43.361554Z",
      "href": "https://localhost:3000/api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
      "gateways": [
        "608509"
      ]
    }
  ]
}
Schema
{
  "properties": {
    "data": {
      "items": {
        "properties": {
          "links": {
            "items": {
              "properties": {
                "end": {
                  "description": "End address for this link",
                  "type": "string"
                },
                "linkQuality": {
                  "description": "Link quality for this link (-dBm)",
                  "type": "integer"
                },
                "start": {
                  "description": "Start address for this link",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "id": {
            "description": "Unique identifier for this topology resource",
            "type": "string"
          },
          "createdAt": {
            "description": "Topology creation date (ISO8601 format)",
            "type": "string"
          },
          "href": {
            "description": "URI for this topology resource",
            "type": "string"
          },
          "gateways": {
            "items": {
              "description": "Gateway MAC address",
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

Initiate Generation of the SNAP Network Topology
POST/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  202
HideShow
Headers
Location: https://localhost:3000/api/v1/tasks/83f4e242-e89d-407b-95e5-a5a603427217

Delete all topologies
DELETE/api/v1/topologies

Delete from storage all previously generated topologies.

Example URI

DELETE /api/v1/topologies
Response  204

SNAP Network Topology

Get topology
GET/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
HideShow
topologyId
string (required) Example: 525a2d06-bfa4-4ad5-b3a1-c614bc367d9c

Unique identifier for a topology, or latest to refer to the topology with the most recent createdAt timestamp

Response  200
HideShow
Body
{
  "data": {
    "links": [
      {
        "end": "5ecad4",
        "linkQuality": 71,
        "start": "608509"
      },
      {
        "end": "608509",
        "linkQuality": 68,
        "start": "5ecad4"
      }
    ],
    "id": "525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
    "createdAt": "2016-07-27T13:57:43.361554Z",
    "href": "https://localhost:3000/api/v1/topologies/525a2d06-bfa4-4ad5-b3a1-c614bc367d9c",
    "gateways": [
      "608509"
    ]
  }
}
Schema
{
  "properties": {
    "data": {
      "properties": {
        "links": {
          "items": {
            "properties": {
              "end": {
                "description": "End address for this link",
                "type": "string"
              },
              "linkQuality": {
                "description": "Link quality for this link (-dBm)",
                "type": "integer"
              },
              "start": {
                "description": "Start address for this link",
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "id": {
          "description": "Unique identifier for this topology resource",
          "type": "string"
        },
        "createdAt": {
          "description": "Topology creation date (ISO8601 format)",
          "type": "string"
        },
        "href": {
          "description": "URI for this topology resource",
          "type": "string"
        },
        "gateways": {
          "items": {
            "description": "Gateway MAC address",
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
Response  404
HideShow

No 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 topology
DELETE/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
HideShow
topologyId
string (required) Example: 525a2d06-bfa4-4ad5-b3a1-c614bc367d9c

Unique identifier for a topology, or latest to refer to the topology with the most recent createdAt timestamp

Response  204
Response  404
HideShow

No device found for this identifier.

Body
{
  "error": {
    "message": "Topology could not be found"
  }
}
Schema
{
  "properties": {
    "error": {
      "properties": {
        "message": {
          "type": "string"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Generated by aglio on 27 Sep 2016