Skip to end of metadata
Go to start of metadata

The Provisioning interface helps vendors/developers initialize and manage large numbers of connected devices. 

Typical activation workflow is:

  1. device calls "activate" method with serial number - server side thing is created
  2. device retrieves current version expected by server side thing
  3. device downloads version specific firmware and perform on-device update
  4. device confirms its version

Typical device owner required upgrade is:

  1. thing owner specify a version he wants to update to 
  2. device retrieves the version to update to
  3. device downloads version specific firmware and perform on-device update
  4. device calls server to update/switch service-side version

Typical periodical upgrade is:

  1. devices retrieves a list of available upgrade versions 
  2. device downloads specific firmware and perform on-device update
  3. 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.

 

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API REST Tip'.

1. Request

PUT /<api-version>/things/activate/<serialNumber>.<format>

ParameterRequiredTypeDefaultDescription

api-version

xstring-

API version. Currently v1.

serialNumberxstring-Device serial number.

format

xstring-

Request/response format. Currently supported format is json.

 

2. Response Status

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API HTTP Response - Get'.


3. Response Body

Activation details:

AttributeRequiredTypeDefaultInformation
thingIdxstring-Activated thing id, must be stored for further API call.
apiKeyxstring-API Key with admin rights to access activated thin.

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Spacer'.

 

4. Examples

Request
Response

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API MAPI Outdated'.
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Messaging Tip'.

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 

serialNumber

xstring

Device serial number.

 

2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

result

xobject-

Activation details

thingIdxstring-Activated thing id, must be stored for further API call.
apiKeyxstring-API Key with admin rights to access activated thin.

 

3. Example

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Mosquitto'.

Request
Response

 

Get thing current version


Retrieves server side thing version.

 

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API REST Tip'.

1. Request

GET /<api-version>/things/<thingId>/versions/current.<format>

ParameterRequiredTypeDefaultDescription

api-version

xstring-

API version. Currently v1.

thingIdxstring-Thing Id.

format

xstring-

Request/response format. Currently supported format is json.

 

2. Response Status

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API HTTP Response - Get'.


3. Response Body

Information about current version:

AttributeRequiredTypeDefaultInformation
idxstring-Current version Id
namexstring-Current version name
description stringnullCurrent version description

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Spacer'.

 

4. Examples

Request
Response
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API MAPI Outdated'.
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Messaging Tip'.

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstring-Thing Id.


2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

result

xarray

Current version information

idxstring-Current version Id
namexstring-Current version name
description stringnullCurrent version description

 

3. Example

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Mosquitto'.

Request
Response

 

Get thing target version


Retrieves thing version to switch to or current server-side thing version otherwise.

 

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API REST Tip'.

1. Request

GET /<api-version>/things/<thingId>/versions/target.<format>

ParameterRequiredTypeDefaultDescription

api-version

xstring-

API version. Currently v1.

thingIdxstring-Thing Id.

format

xstring-

Request/response format. Currently supported format is json.

 

2. Response Status

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API HTTP Response - Get'.


3. Response Body

Information about target version:

AttributeRequiredTypeDefaultInformation
idxstring-Current version Id
namexstring-Current version name
description stringnullCurrent version description

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Spacer'.

 

4. Examples

Request
Response
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API MAPI Outdated'.
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Messaging Tip'.

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstringnullThing Id.


2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

result

xarray

Target version information

idxstring-Target version Id
namexstring-Target version name
description stringnullTarget version description

 

3. Example

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Mosquitto'.

Request
Response

Get version firmware


Retrieves firmware associated with a specific version.

 

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API REST Tip'.

1. Request

GET /<api-version>/things/<thingId>/versions/<versionId>/firmware.<format>

ParameterRequiredTypeDefaultDescription

api-version

xstring-

API version. Currently v1.

thingIdxstring-Thing Id.
versionIdxstring-Version Id.

format

xstring-

Request/response format. Currently supported format is json.

 

2. Response Status

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API HTTP Response - Get'.


3. Response Body

Encoded firmware

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Spacer'.

 

4. Examples

Request
Response
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API MAPI Outdated'.
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Messaging Tip'.

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstring-Thing Id.
versionIdxstring-Version Id.


2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

result

 stringnull

Encoded firmware

 

3. Example

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Mosquitto'.

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.

 

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API REST Tip'.

1. Request

GET /<api-version>/things/<thingId>/versions/<versionId>/updates.<format>

ParameterRequiredTypeDefaultDescription

api-version

xstring-

API version. Currently v1.

thingIdxstring-Thing Id.
versionIdxstring-Version Id.

format

xstring-

Request/response format. Currently supported format is json.

 

2. Response Status

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API HTTP Response - Get'.


3. Response Body

Array with information on versions:

AttributeRequiredTypeDefaultInformation
idxstring-Version Id
namexstring-Version name
description stringnullVersion description

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'Spacer'.

 

4. Examples

Request
Response
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API MAPI Outdated'.
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Messaging Tip'.

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstringnullThing Id.
versionIdxstringnullVersion Id.


2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

result

xarray

Array of versions

idxstring-Version Id
namexstring-Version name
description stringnullVersion description

 

3. Example

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Mosquitto'.

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.

 

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API REST Tip'.

1. Request

PUT /<api-version>/things/<thingId>/versions/<versionId>/switch.<format>

ParameterRequiredTypeDefaultDescription

api-version

xstring-

API version. Currently v1.

thingId

xstring-

Identifier of a thing.

versionIdxstring-Version Id to switch/update to.

format

xstring-

Request/response format. Currently supported format is json.

 

2. Response Status

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API HTTP Response - Update'.


3. Examples

Request
Response
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API MAPI Outdated'.
Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Messaging Tip'.

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 

thingId

xstring-

Identifier of a thing.

versionIdxstring-Version Id to switch/update to.

 

2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

3. Example

Error rendering macro 'excerpt-include' : User 'null' does not have permission to view the page 'API Mosquitto'.

Request
Response
  • No labels