Back to top

SNAP Thing Services API

SNAP Thing Services API Version 1.3.0

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

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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "message": {
        "type": "string"
      }
    }
  }
}

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

Could not get network settings.

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

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

Example URI

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

Could not update network settings.

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

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": [
    {
      "href": "https://localhost:3000/api/v1/dc/dc1",
      "id": 1,
      "queryFunction": "data",
      "deviceTypes": [
        "sensors"
      ],
      "name": "dc1",
      "pollInterval": 60
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URI for this data collector resource"
          },
          "id": {
            "type": "integer",
            "description": "Unique identifier for this data collector"
          },
          "queryFunction": {
            "type": "string",
            "description": "Name of query function"
          },
          "deviceTypes": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "Description of device type"
            }
          },
          "name": {
            "type": "string",
            "description": "Name of data collector"
          },
          "pollInterval": {
            "type": "integer",
            "description": "Number of seconds between polls"
          }
        }
      }
    }
  }
}

Create a data collector
POST/api/v1/dc

Example URI

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

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

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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

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": {
    "href": "https://localhost:3000/api/v1/dc/dc1",
    "id": 1,
    "queryFunction": "data",
    "deviceTypes": [
      "sensors"
    ],
    "name": "dc1",
    "pollInterval": 60
  }
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "href": {
          "type": "string",
          "description": "URI for this data collector resource"
        },
        "id": {
          "type": "integer",
          "description": "Unique identifier for this data collector"
        },
        "queryFunction": {
          "type": "string",
          "description": "Name of query function"
        },
        "deviceTypes": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "Description of device type"
          }
        },
        "name": {
          "type": "string",
          "description": "Name of data collector"
        },
        "pollInterval": {
          "type": "integer",
          "description": "Number of seconds between polls"
        }
      }
    }
  }
}

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

Devices

Device Collection

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

Example URI

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

Limit result to devices with this device type

expand
string (optional) Example: firmware,image

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

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

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
{
  "platform": "RF200",
  "description": "Device1",
  "addr": "ccddee",
  "deviceType": "Deck1"
}
Schema
{
  "type": "object",
  "description": "A device",
  "title": "Add device",
  "required": [
    "addr",
    "description",
    "platform",
    "deviceType"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#",
  "properties": {
    "platform": {
      "type": "string",
      "description": "The device platform (ex: RF200)"
    },
    "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\").",
      "type": "string",
      "description": "SNAP Mac Address",
      "pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$"
    },
    "description": {
      "type": "string",
      "description": "Description of the device"
    },
    "deviceType": {
      "type": "string",
      "description": "The type of device. This must exist in the database already."
    }
  }
}
Response  201
HideShow
Headers
Location: https://localhost:3000/api/v1/devices/6
Content-Type: application/json
Body
{
  "data": {
    "href": "https://localhost:3000/api/v1/devices/6",
    "id": 6,
    "description": "Device1",
    "image": {
      "href": "Unknown"
    },
    "deviceType": "Deck1",
    "upgrading": false,
    "firmware": {
      "href": "Unknown"
    },
    "platform": "RF200",
    "addr": "ccddee"
  }
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "href": {
          "type": "string",
          "description": "URI for this device resource"
        },
        "id": {
          "type": "integer",
          "description": "Unique identifier for device"
        },
        "description": {
          "type": "string",
          "description": "Description of device"
        },
        "deviceType": {
          "type": "string",
          "description": "Type of device"
        },
        "upgrading": {
          "type": "boolean",
          "description": "Indicates whether device is upgrading"
        },
        "platform": {
          "type": "string",
          "description": "Type of platform"
        },
        "addr": {
          "type": "string",
          "description": "Address of device"
        }
      }
    }
  }
}
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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}
Response  404
HideShow

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

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

No 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 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
{
  "platform": "RF200",
  "description": "Device1",
  "addr": "ccddee",
  "deviceType": "Deck1"
}
Schema
{
  "title": "Update device",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "A device",
  "properties": {
    "platform": {
      "type": "string",
      "description": "The device platform (ex: RF200)"
    },
    "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\").",
      "type": "string",
      "description": "SNAP Mac Address",
      "pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$"
    },
    "description": {
      "type": "string",
      "description": "Description of the device"
    },
    "deviceType": {
      "type": "string",
      "description": "The type of device. This must exist in the database already."
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "href": "https://localhost:3000/api/v1/devices/6",
    "id": 6,
    "description": "Device1",
    "image": {
      "href": "Unknown"
    },
    "deviceType": "Deck1",
    "upgrading": false,
    "firmware": {
      "href": "Unknown"
    },
    "platform": "RF200",
    "addr": "ccddee"
  }
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "href": {
          "type": "string",
          "description": "URI for this device resource"
        },
        "description": {
          "type": "string",
          "description": "Description of device"
        },
        "id": {
          "type": "integer",
          "description": "Unique identifier for device"
        },
        "image": {
          "type": "object",
          "description": "Image of device",
          "properties": {
            "href": {
              "type": "string",
              "description": "URI for this image resource"
            }
          }
        },
        "deviceType": {
          "type": "string",
          "description": "Type of device"
        },
        "upgrading": {
          "type": "boolean",
          "description": "Indicates whether device is upgrading"
        },
        "firmware": {
          "type": "object",
          "description": "Firmware of device",
          "properties": {
            "href": {
              "type": "string",
              "description": "URI for this firmware resource"
            }
          }
        },
        "platform": {
          "type": "string",
          "description": "Type of platform"
        },
        "addr": {
          "type": "string",
          "description": "Address of device"
        }
      }
    }
  }
}
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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}
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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}
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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

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

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

Some 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 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": [
    {
      "href": "https://localhost:3000/api/v1/deviceTypes/",
      "id": 1,
      "description": "Some Device Type"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "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"
          }
        }
      }
    }
  }
}

Create device type
POST/api/v1/deviceTypes

Example URI

POST /api/v1/deviceTypes
Request
HideShow
Body
{
  "description": "Some Device Type"
}
Schema
{
  "type": "object",
  "description": "A device type",
  "title": "Add device type",
  "required": [
    "description"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#",
  "properties": {
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "A unique device type"
    }
  }
}
Response  201
HideShow
Headers
Location: https://localhost:3000/api/v1/deviceTypes/1
Content-Type: application/json
Body
{
  "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  409
HideShow

A 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

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": [
    {
      "href": "https://localhost:3000/api/v1/deviceTypes/1",
      "id": 1,
      "description": "Some Device Type"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "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"
          }
        }
      }
    }
  }
}

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",
  "description": "A device type",
  "title": "Update device type",
  "required": [
    "description"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#",
  "properties": {
    "description": {
      "type": "string",
      "minLength": 1,
      "description": "Type of device"
    }
  }
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "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  404
HideShow

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

Some 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 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
{
  "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 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": [
    {
      "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": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URI for this firmware resource"
          },
          "version": {
            "type": "string",
            "description": "Firmware version number"
          }
        },
        "description": "A SNAP firmware release"
      }
    }
  }
}

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": {
    "href": "https://localhost:3000/api/v1/firmware/2.7.1",
    "version": "2.7.1"
  }
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "href": {
          "type": "string",
          "description": "URI for this firmware resource"
        },
        "version": {
          "type": "string",
          "description": "Firmware version number"
        }
      },
      "description": "A SNAP firmware release"
    }
  }
}
Response  404
HideShow

There 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

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": {
    "siteDoctor": true,
    "customer": "John Smith",
    "siteDirector": true,
    "types": [
      "manage",
      "deploy"
    ],
    "expiration": "2020-02-05",
    "dataCollector": true
  }
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "siteDoctor": {
          "type": "boolean",
          "description": "True if the Site Doctor is licensed"
        },
        "customer": {
          "type": "string",
          "description": "The licensed customer"
        },
        "siteDirector": {
          "type": "boolean",
          "description": "True if the Site Director is licensed"
        },
        "types": {
          "type": "array",
          "items": {
            "type": "string",
            "description": "License types"
          }
        },
        "expiration": {
          "type": "string",
          "description": "The date the license expires"
        },
        "dataCollector": {
          "type": "boolean",
          "description": "True if the Data Collector is licensed"
        }
      }
    }
  }
}

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

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

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

No 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 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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

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": [
    {
      "href": "https://localhost:3000/api/v1/moduleTypes/RF200PF1",
      "partName": "RF200PF1"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URI for this Synapse RF Module Type"
          },
          "partName": {
            "type": "string",
            "description": "Synapse RF Module Type Part Name"
          }
        }
      }
    }
  }
}

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": [
    {
      "href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
      "deviceGroupConfigurations": [
        {
          "devices": [
            "03cd71",
            "04ab44"
          ],
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
            }
          }
        },
        {
          "devices": [
            "00a400",
            "040128"
          ],
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
            }
          }
        }
      ],
      "id": "7e968754-78f0-09f8-b57b-968745b2789e"
    },
    {
      "href": "https://localhost:3000/api/v1/networkConfigurations/c5fe2546-78f0-09f8-b57b-968745b2789e",
      "deviceGroupConfigurations": [
        {
          "devices": [
            "082614",
            "7531df"
          ],
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/4d271412-33f0-47d4-a01e-973593e1915d"
            }
          }
        },
        {
          "devices": [
            "04abaf",
            "604def"
          ],
          "configuration": {
            "image": {
              "href": "https://localhost:3000/api/v1/images/9e524135-3a66-49c0-9126-98c901cd6ee4"
            }
          }
        }
      ],
      "id": "c5fe2546-78f0-09f8-b57b-968745b2789e"
    }
  ]
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "URI for this network configuration resource"
          },
          "deviceGroupConfigurations": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "devices": {
                  "type": "array",
                  "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').",
                    "type": "string",
                    "pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
                    "description": "SNAP Mac address"
                  },
                  "description": "A group of devices",
                  "uniqueItems": true
                },
                "configuration": {
                  "type": "object",
                  "properties": {
                    "firmware": {
                      "type": "object",
                      "properties": {
                        "href": {
                          "type": "string",
                          "description": "Location"
                        }
                      },
                      "description": "A SNAP firmware release"
                    },
                    "image": {
                      "type": "object",
                      "properties": {
                        "href": {
                          "type": "string",
                          "description": "Location"
                        }
                      },
                      "description": "A SPY image"
                    }
                  },
                  "description": "A configuration that can be applied to one or more devices"
                }
              },
              "description": "Associates a configuration with a group of devices"
            }
          },
          "id": {
            "type": "string",
            "description": "Unique identifier for this network configuration"
          }
        },
        "description": "A network configuration"
      }
    }
  }
}

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": [
    {
      "devices": [
        "03cd71",
        "04ab44"
      ],
      "configuration": {
        "image": {
          "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
        }
      }
    },
    {
      "devices": [
        "00a400",
        "040128"
      ],
      "configuration": {
        "image": {
          "href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
        }
      }
    }
  ]
}
Schema
{
  "type": "object",
  "description": "A network configuration",
  "title": "Add network configuration",
  "required": [
    "deviceGroupConfigurations"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#",
  "properties": {
    "deviceGroupConfigurations": {
      "type": "array",
      "items": {
        "required": [
          "devices"
        ],
        "type": "object",
        "properties": {
          "devices": {
            "type": "array",
            "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\").",
              "type": "string",
              "pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
              "description": "SNAP Mac address"
            },
            "description": "A group of devices",
            "uniqueItems": true
          },
          "configuration": {
            "type": "object",
            "properties": {
              "firmware": {
                "type": "object",
                "properties": {
                  "href": {
                    "type": "string",
                    "description": "Location"
                  }
                },
                "description": "A SNAP firmware release"
              },
              "image": {
                "type": "object",
                "properties": {
                  "href": {
                    "type": "string",
                    "description": "Location"
                  }
                },
                "description": "A SPY image"
              }
            },
            "description": "A configuration that can be applied to one or more devices"
          }
        },
        "description": "Associates a configuration with a group of devices"
      }
    }
  }
}
Response  201
HideShow
Headers
Location: https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e
Body
{
  "data": {
    "href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
    "deviceGroupConfigurations": [
      {
        "devices": [
          "03cd71",
          "04ab44"
        ],
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
          }
        }
      },
      {
        "devices": [
          "00a400",
          "040128"
        ],
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
          }
        }
      }
    ],
    "id": "7e968754-78f0-09f8-b57b-968745b2789e"
  }
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "required": [
        "deviceGroupConfigurations"
      ],
      "type": "object",
      "properties": {
        "href": {
          "type": "string",
          "description": "URI for this network configuration resource"
        },
        "deviceGroupConfigurations": {
          "type": "array",
          "items": {
            "required": [
              "devices"
            ],
            "type": "object",
            "properties": {
              "devices": {
                "type": "array",
                "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').",
                  "type": "string",
                  "pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
                  "description": "SNAP Mac address"
                },
                "description": "A group of devices",
                "uniqueItems": true
              },
              "configuration": {
                "type": "object",
                "properties": {
                  "firmware": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string",
                        "description": "Location"
                      }
                    },
                    "description": "A SNAP firmware release"
                  },
                  "image": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string",
                        "description": "Location"
                      }
                    },
                    "description": "A SPY image"
                  }
                },
                "description": "A configuration that can be applied to one or more devices"
              }
            },
            "description": "Associates a configuration with a group of devices"
          }
        },
        "id": {
          "type": "string",
          "description": "Unique identifier for this network configuration"
        }
      },
      "description": "A network configuration"
    }
  }
}

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": {
    "href": "https://localhost:3000/api/v1/networkConfigurations/7e968754-78f0-09f8-b57b-968745b2789e",
    "deviceGroupConfigurations": [
      {
        "devices": [
          "03cd71",
          "04ab44"
        ],
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/6f992502-33f0-47d4-a01e-973593e1915d"
          }
        }
      },
      {
        "devices": [
          "00a400",
          "040128"
        ],
        "configuration": {
          "image": {
            "href": "https://localhost:3000/api/v1/images/4a2fd398-3a66-49c0-9126-98c901cd6ee4"
          }
        }
      }
    ],
    "id": "7e968754-78f0-09f8-b57b-968745b2789e"
  }
}
Schema
{
  "type": "object",
  "properties": {
    "data": {
      "required": [
        "deviceGroupConfigurations"
      ],
      "type": "object",
      "properties": {
        "href": {
          "type": "string",
          "description": "URI for this network configuration resource"
        },
        "deviceGroupConfigurations": {
          "type": "array",
          "items": {
            "required": [
              "devices"
            ],
            "type": "object",
            "properties": {
              "devices": {
                "type": "array",
                "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').",
                  "type": "string",
                  "pattern": "^(00[.:]?1[cC][.:]?2[cC][.:]?[0-9a-fA-F]{2}[.:]?[0-9a-fA-F]{2}[.:]?)?([0-9a-fA-F][.:]?){5}[0-9a-fA-F]$",
                  "description": "SNAP Mac address"
                },
                "description": "A group of devices",
                "uniqueItems": true
              },
              "configuration": {
                "type": "object",
                "properties": {
                  "firmware": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string",
                        "description": "Location"
                      }
                    },
                    "description": "A SNAP firmware release"
                  },
                  "image": {
                    "type": "object",
                    "properties": {
                      "href": {
                        "type": "string",
                        "description": "Location"
                      }
                    },
                    "description": "A SPY image"
                  }
                },
                "description": "A configuration that can be applied to one or more devices"
              }
            },
            "description": "Associates a configuration with a group of devices"
          }
        },
        "id": {
          "type": "string",
          "description": "Unique identifier for this network configuration"
        }
      },
      "description": "A network configuration"
    }
  }
}
Response  404
HideShow

No network configuration found for this identifier.

Body
{
  "error": {
    "message": "Network configuration 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 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",
  "description": "A network configuration location",
  "title": "Apply a network configuration update",
  "required": [
    "href"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#",
  "properties": {
    "href": {
      "type": "string",
      "description": "The location of a network configuration"
    }
  }
}
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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}
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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}
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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

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

No such results

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

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": {
    "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  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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

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

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

No 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 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
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        }
      }
    }
  }
}

Generated by aglio on 12 Oct 2016