The Provisioning interface helps vendors/developers initialize and manage large numbers of connected devices.
Typical activation workflow is:
- device calls "activate" method with serial number - server side thing is created
- device retrieves current version expected by server side thing
- device downloads version specific firmware and perform on-device update
- device confirms its version
Typical device owner required upgrade is:
- thing owner specify a version he wants to update to
- device retrieves the version to update to
- device downloads version specific firmware and perform on-device update
- device calls server to update/switch service-side version
Typical periodical upgrade is:
- devices retrieves a list of available upgrade versions
- device downloads specific firmware and perform on-device update
- device calls server to update/switch service-side version
Activate
Activates thing by its serial number. If thing with the specified serial number does not exists, then it's created and a dedicated admin API Key is generated for its access. If the thing already exists then it's not changed, but an old API Key is dropped and a a new one is generated.
The page API REST Tip does not exist.
1. Request
PUT /<api-version>/things/activate/<serialNumber>.<format>
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
|
api-version |
x | string | - |
API version. Currently v1. |
| serialNumber | x | string | - | Device serial number. |
|
format |
x | string | - |
Request/response format. Currently supported format is json. |
2. Response Status
The page API HTTP Response - Get does not exist.
3. Response Body
Activation details:
| Attribute | Required | Type | Default | Information |
|---|---|---|---|---|
| thingId | x | string | - | Activated thing id, must be stored for further API call. |
| apiKey | x | string | - | API Key with admin rights to access activated thin. |
The page Spacer does not exist.
4. Examples
Request
Response
The page API MAPI Outdated does not exist.The page API Messaging Tip does not exist.
1. Request
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier established by the client | |
|
serialNumber |
x | string | - |
Device serial number. |
2. Response
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier specified in request | |
|
result |
x | object | - |
Activation details |
| →thingId | x | string | - | Activated thing id, must be stored for further API call. |
| →apiKey | x | string | - | API Key with admin rights to access activated thin. |
3. Example
The page API Mosquitto does not exist.
Request
Response
Get thing current version
Retrieves server side thing version.
The page API REST Tip does not exist.
1. Request
GET /<api-version>/things/<thingId>/versions/current.<format>
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
|
api-version |
x | string | - |
API version. Currently v1. |
| thingId | x | string | - | Thing Id. |
|
format |
x | string | - |
Request/response format. Currently supported format is json. |
2. Response Status
The page API HTTP Response - Get does not exist.
3. Response Body
Information about current version:
| Attribute | Required | Type | Default | Information |
|---|---|---|---|---|
| id | x | string | - | Current version Id |
| name | x | string | - | Current version name |
| description | string | null | Current version description |
The page Spacer does not exist.
4. Examples
Request
Response
The page API MAPI Outdated does not exist.The page API Messaging Tip does not exist.
1. Request
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier established by the client | |
| thingId | x | string | - | Thing Id. |
2. Response
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier specified in request | |
|
result |
x | array | - |
Current version information |
| →id | x | string | - | Current version Id |
| →name | x | string | - | Current version name |
| →description | string | null | Current version description |
3. Example
The page API Mosquitto does not exist.
Request
Response
Get thing target version
Retrieves thing version to switch to or current server-side thing version otherwise.
The page API REST Tip does not exist.
1. Request
GET /<api-version>/things/<thingId>/versions/target.<format>
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
|
api-version |
x | string | - |
API version. Currently v1. |
| thingId | x | string | - | Thing Id. |
|
format |
x | string | - |
Request/response format. Currently supported format is json. |
2. Response Status
The page API HTTP Response - Get does not exist.
3. Response Body
Information about target version:
| Attribute | Required | Type | Default | Information |
|---|---|---|---|---|
| id | x | string | - | Current version Id |
| name | x | string | - | Current version name |
| description | string | null | Current version description |
The page Spacer does not exist.
4. Examples
Request
Response
The page API MAPI Outdated does not exist.The page API Messaging Tip does not exist.
1. Request
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier established by the client | |
| thingId | x | string | null | Thing Id. |
2. Response
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier specified in request | |
|
result |
x | array | - |
Target version information |
| →id | x | string | - | Target version Id |
| →name | x | string | - | Target version name |
| →description | string | null | Target version description |
3. Example
The page API Mosquitto does not exist.
Request
Response
Get version firmware
Retrieves firmware associated with a specific version.
The page API REST Tip does not exist.
1. Request
GET /<api-version>/things/<thingId>/versions/<versionId>/firmware.<format>
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
|
api-version |
x | string | - |
API version. Currently v1. |
| thingId | x | string | - | Thing Id. |
| versionId | x | string | - | Version Id. |
|
format |
x | string | - |
Request/response format. Currently supported format is json. |
2. Response Status
The page API HTTP Response - Get does not exist.
3. Response Body
Encoded firmware
The page Spacer does not exist.
4. Examples
Request
Response
The page API MAPI Outdated does not exist.The page API Messaging Tip does not exist.
1. Request
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier established by the client | |
| thingId | x | string | - | Thing Id. |
| versionId | x | string | - | Version Id. |
2. Response
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier specified in request | |
|
result |
string | null |
Encoded firmware |
3. Example
The page API Mosquitto does not exist.
Request
Response
Get versions available for thing to switch to
Retrieves a list of versions available for thing to switch to from a specific version.
The page API REST Tip does not exist.
1. Request
GET /<api-version>/things/<thingId>/versions/<versionId>/updates.<format>
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
|
api-version |
x | string | - |
API version. Currently v1. |
| thingId | x | string | - | Thing Id. |
| versionId | x | string | - | Version Id. |
|
format |
x | string | - |
Request/response format. Currently supported format is json. |
2. Response Status
The page API HTTP Response - Get does not exist.
3. Response Body
Array with information on versions:
| Attribute | Required | Type | Default | Information |
|---|---|---|---|---|
| id | x | string | - | Version Id |
| name | x | string | - | Version name |
| description | string | null | Version description |
The page Spacer does not exist.
4. Examples
Request
Response
The page API MAPI Outdated does not exist.The page API Messaging Tip does not exist.
1. Request
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier established by the client | |
| thingId | x | string | null | Thing Id. |
| versionId | x | string | null | Version Id. |
2. Response
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier specified in request | |
|
result |
x | array | - |
Array of versions |
| →id | x | string | - | Version Id |
| →name | x | string | - | Version name |
| →description | string | null | Version description |
3. Example
The page API Mosquitto does not exist.
Request
Response
Switch thing to a new version
Switches server side version to a specific version or confirms that thing firmware was switched to a specific version.
The page API REST Tip does not exist.
1. Request
PUT /<api-version>/things/<thingId>/versions/<versionId>/switch.<format>
| Parameter | Required | Type | Default | Description |
|---|---|---|---|---|
|
api-version |
x | string | - |
API version. Currently v1. |
| x | string | - |
Identifier of a thing. |
|
| versionId | x | string | - | Version Id to switch/update to. |
|
format |
x | string | - |
Request/response format. Currently supported format is json. |
2. Response Status
The page API HTTP Response - Update does not exist.
3. Examples
Request
Response
The page API MAPI Outdated does not exist.The page API Messaging Tip does not exist.
1. Request
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier established by the client | |
| x | string | - |
Identifier of a thing. |
|
| versionId | x | string | - | Version Id to switch/update to. |
2. Response
| Attribute | Required | Type | Default | Description |
|---|---|---|---|---|
| id | string | null | Request identifier specified in request |
3. Example
The page API Mosquitto does not exist.
Request
Response