Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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
Div
idapi-content

Table of Contents
stylesquare

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.

 

Localtab Group
verticaltrue
Localtab
activetrue
titleREST
Excerpt Include
API REST Tip
API REST Tip
nopaneltrue

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

Excerpt Include
API HTTP Response - Get
API HTTP Response - Get
nopaneltrue


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.

Excerpt Include
Spacer
Spacer
nopaneltrue

Localtab Group
Localtab
titlejson
Code Block
languagejs
{
   "thingId":<thing_id>,
   "apiKey":<api_key>
}

 

4. Examples

Localtab
activetrue
titleREST
Localtab Group
Localtab
titlejson
Code Block
languagejs
titleRequest
PUT /v1/things/activate/1234567890.json
Code Block
languagejs
titleResponse
200 OK
 
{
	"apiKey":"31370dd83fa249529722bd86dddb1bf6",
	"thingId":"a7a6f057af5611e28b7d6c626dd90e00"	
}
Localtab
titleMessaging

Excerpt Include
API MAPI Outdated
API MAPI Outdated
nopaneltrue
Excerpt Include
API Messaging Tip
API Messaging Tip
nopaneltrue

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 

serialNumber

xstring

Device serial number.

Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":"7755",
	"method":"things.activate",
	"params": {
		"serialNumber":"1234567890"
	}
}

 

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.
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"result": {
		"thingId":<thing_id>,
		"apiKey":<api_key>
	}
}

 

3. Example

Localtab Group
Localtab
titlemqtt

Excerpt Include
API Mosquitto
API Mosquitto
nopaneltrue

Code Block
languagepowershell
mosquitto_pub -d -h api.gadgetkeeper.com -t "v1.json" -m "{\"jsonrpc\":\"2.0\",\"id\":\"7755\",\"method\":\"things.activate\",\"params\":{\"serialNumber\":\"1234567890\"}}"
Code Block
languagejs
titleRequest
{
	"jsonrpc":"2.0",
	"id":"7755",
	"method":"things.activate",
	"params": {
		"serialNumber":"1234567890"
	}
}
Code Block
languagejs
titleResponse
{
    "jsonrpc":"2.0",
    "id":"7755",
	"result": {
		"apiKey":"31370dd83fa249529722bd86dddb1bf6",
		"thingId":"a7a6f057af5611e28b7d6c626dd90e00"
	}
}

 

Get thing current version


Retrieves server side thing version.

 

Localtab Group
verticaltrue
Localtab
activetrue
titleREST
Excerpt Include
API REST Tip
API REST Tip
nopaneltrue

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

Excerpt Include
API HTTP Response - Get
API HTTP Response - Get
nopaneltrue


3. Response Body

Information about current version:

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

Excerpt Include
Spacer
Spacer
nopaneltrue

Localtab Group
Localtab
titlejson
Code Block
languagejs
{
   "id":<version id>,
   "name":<version name>,
   "description":<version description>
}

 

4. Examples

Localtab
activetrue
titleREST
Localtab Group
Localtab
titlejson
Code Block
languagejs
titleRequest
GET /v1/things/de629f2d3ecf4e7097be533dc88c18c8/versions/current.json
Code Block
languagejs
titleResponse
200 OK
 
{
	"id":"9dc6f830032611e3a03f6c626dd90e00",
	"name":"3.1",
	"description":"upgraded version"
}
Localtab
titleMessaging
Excerpt Include
API MAPI Outdated
API MAPI Outdated
nopaneltrue
Excerpt Include
API Messaging Tip
API Messaging Tip
nopaneltrue

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstring-Thing Id.
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"method":"things.versions.current.get",
	"params": {
		"thingId":<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
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"result": {
		"id":<version_id>,
		"name":<version_name>,
		"name":<version_description>
	}
}

 

3. Example

Localtab Group
Localtab
titlemqtt

Excerpt Include
API Mosquitto
API Mosquitto
nopaneltrue

Code Block
languagepowershell
mosquitto_pub -d -h api.gadgetkeeper.com -t "v1.f628d91dbda2499eb70cd9ac1a1ad50d.json" -m "{\"jsonrpc\":\"2.0\",\"id\":\"7755\",\"method\":\"things.versions.current.get\", \"params\": {\"thingId\":\"de629f2d3ecf4e7097be533dc88c18c8\"}}"
Code Block
languagejs
titleRequest
{
	"jsonrpc":"2.0",
	"id":"7755",
	"method":"things.versions.current.get",
	"params": {
		"thingId":"de629f2d3ecf4e7097be533dc88c18c8"
	}
}
Code Block
titleResponse
{
    "jsonrpc":"2.0",
    "id":"7755",
	"result": {
		"id":"9dc6f830032611e3a03f6c626dd90e00", 
		"name":"3.1",
		"description": "updated version"
	}
}

 

Get thing target version


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

 

Localtab Group
verticaltrue
Localtab
activetrue
titleREST
Excerpt Include
API REST Tip
API REST Tip
nopaneltrue

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

Excerpt Include
API HTTP Response - Get
API HTTP Response - Get
nopaneltrue


3. Response Body

Information about target version:

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

Excerpt Include
Spacer
Spacer
nopaneltrue

Localtab Group
Localtab
titlejson
Code Block
languagejs
{
   "id":<version_id>,
   "name":<version_name>,
   "description":<version_description>
}

 

4. Examples

Localtab
activetrue
titleREST
Localtab Group
Localtab
titlejson
Code Block
languagejs
titleRequest
GET /v1/things/de629f2d3ecf4e7097be533dc88c18c8/versions/target.json
Code Block
languagejs
titleResponse
200 OK
 
{
	"id":"9dc6f830032611e3a03f6c626dd90e00",
	"name":"3.1",
	"description":"upgraded version"
}
Localtab
titleMessaging
Excerpt Include
API MAPI Outdated
API MAPI Outdated
nopaneltrue
Excerpt Include
API Messaging Tip
API Messaging Tip
nopaneltrue

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstringnullThing Id.
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"method":"things.versions.target.get",
	"params": {
		"thingId":<thing_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
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"result": {
		"id":<version_id>,
		"name":<version_name>,
		"name":<version_description>
	}
}

 

3. Example

Localtab Group
Localtab
titlemqtt

Excerpt Include
API Mosquitto
API Mosquitto
nopaneltrue

Code Block
languagepowershell
mosquitto_pub -d -h api.gadgetkeeper.com -t "v1.f628d91dbda2499eb70cd9ac1a1ad50d.json" -m "{\"jsonrpc\":\"2.0\",\"id\":\"7755\",\"method\":\"things.versions.target.get\", \"params\": {\"thingId\":\"de629f2d3ecf4e7097be533dc88c18c8\"}}"
Code Block
languagejs
titleRequest
{
	"jsonrpc":"2.0",
	"id":"7755",
	"method":"things.versions.target.get",
	"params": {
		"thingId":"de629f2d3ecf4e7097be533dc88c18c8"
	}
}
Code Block
titleResponse
{
    "jsonrpc":"2.0",
    "id":"7755",
	"result": {
		"id":"9dc6f830032611e3a03f6c626dd90e00", 
		"name":"3.1",
		"description": "updated version"
	}
}

Get version firmware


Retrieves firmware associated with a specific version.

 

Localtab Group
verticaltrue
Localtab
activetrue
titleREST
Excerpt Include
API REST Tip
API REST Tip
nopaneltrue

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

Excerpt Include
API HTTP Response - Get
API HTTP Response - Get
nopaneltrue


3. Response Body

Encoded firmware

Excerpt Include
Spacer
Spacer
nopaneltrue

Localtab Group
Localtab
titlejson
Code Block
languagejs
<encoded_firmware>

 

4. Examples

Localtab
activetrue
titleREST
Localtab Group
Localtab
titlejson
Code Block
languagejs
titleRequest
GET /v1/things/de629f2d3ecf4e7097be533dc88c18c8/versions/31370dd83fa249529722bd86dddb1bf6/firmware.json
Code Block
languagejs
titleResponse
200 OK
 
"Ynl0ZXNSZXNwb25zZQ=="
Localtab
titleMessaging
Excerpt Include
API MAPI Outdated
API MAPI Outdated
nopaneltrue
Excerpt Include
API Messaging Tip
API Messaging Tip
nopaneltrue

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstring-Thing Id.
versionIdxstring-Version Id.
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"method":"things.versions.firmware.get",
	"params": {
		"thingId":<thing_id>,
		"versionId":<version_id>
	}
}


2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

result

 stringnull

Encoded firmware

Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"result": <encoded_firmware>
}

 

3. Example

Localtab Group
Localtab
titlemqtt

Excerpt Include
API Mosquitto
API Mosquitto
nopaneltrue

Code Block
languagepowershell
mosquitto_pub -d -h api.gadgetkeeper.com -t "v1.f628d91dbda2499eb70cd9ac1a1ad50d.json" -m "{\"jsonrpc\":\"2.0\",\"id\":\"7755\",\"method\":\"things.versions.firmware.get\",\"params\":{ \"thingId\":\"de629f2d3ecf4e7097be533dc88c18c8\",\"versionId\":\"31370dd83fa249529722bd86dddb1bf6\"}}" 
Code Block
languagejs
titleRequest
{
	"jsonrpc":"2.0",
	"id":"7755",
	"method":"things.versions.target.get",
	"params": {
		"thingId":"de629f2d3ecf4e7097be533dc88c18c8",
		"versionId":"31370dd83fa249529722bd86dddb1bf6"
	}
}
Code Block
titleResponse
{
    "jsonrpc":"2.0",
    "id":"7755",
	"result": "Ynl0ZXNSZXNwb25zZQ=="
}

 

Get versions available for thing to switch to


Retrieves a list of versions available for thing to switch to from a specific version.

 

Localtab Group
verticaltrue
Localtab
activetrue
titleREST
Excerpt Include
API REST Tip
API REST Tip
nopaneltrue

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

Excerpt Include
API HTTP Response - Get
API HTTP Response - Get
nopaneltrue


3. Response Body

Array with information on versions:

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

Excerpt Include
Spacer
Spacer
nopaneltrue

Localtab Group
Localtab
titlejson
Code Block
languagejs
[
	{
	   "id":<version_id>,
	   "name":<version_name>,
	   "description":<version_description>
	},
	...
]

 

4. Examples

Localtab
activetrue
titleREST
Localtab Group
Localtab
titlejson
Code Block
languagejs
titleRequest
GET /v1/things/de629f2d3ecf4e7097be533dc88c18c8/versions/31370dd83fa249529722bd86dddb1bf6/updates.json
Code Block
languagejs
titleResponse
200 OK
 
[
   {
      "id":"9dc6f830032611e3a03f6c626dd90e00",
      "name":"2.1"
   },
   {
      "id":"b4864380cb0111e282f384a6c88de33e",
      "name":"2.3",
      "description":"minor interface update"
   }
]
Localtab
titleMessaging
Excerpt Include
API MAPI Outdated
API MAPI Outdated
nopaneltrue
Excerpt Include
API Messaging Tip
API Messaging Tip
nopaneltrue

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 
thingIdxstringnullThing Id.
versionIdxstringnullVersion Id.
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"method":"things.versions.updates.list",
	"params": {
		"thingId":<thing_id>,
		"versionId":<version_id>
	}
}


2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request

result

xarray

Array of versions

idxstring-Version Id
namexstring-Version name
description stringnullVersion description
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"result":[
		{
		   "id":<version_id>,
		   "name":<version_name>,
		   "description":<version_description>
		},
		...
	]
}

 

3. Example

Localtab Group
Localtab
titlemqtt

Excerpt Include
API Mosquitto
API Mosquitto
nopaneltrue

Code Block
languagepowershell
mosquitto_pub -d -h api.gadgetkeeper.com -t "v1.f628d91dbda2499eb70cd9ac1a1ad50d.json" -m "{\"jsonrpc\":\"2.0\",\"id\":\"7755\",\"method\":\"provision.versions.updates.list\",\"params\":{\"params\": \"thingId\":\"de629f2d3ecf4e7097be533dc88c18c8\",\"versionId\":\"31370dd83fa249529722bd86dddb1bf6\"}}"
Code Block
languagejs
titleRequest
{
    "jsonrpc":"2.0",
    "id":"7755",
    "method":"things.versions.updates.list",
    "params": {
        "thingId":"de629f2d3ecf4e7097be533dc88c18c8",
        "versionId":"31370dd83fa249529722bd86dddb1bf6"
    }
}
Code Block
titleResponse
{
    "jsonrpc":"2.0",
    "id":"7755",
	"result":[
	   {
		  "id":"9dc6f830032611e3a03f6c626dd90e00",
		  "name":"2.1"
	   },
	   {
		  "id":"b4864380cb0111e282f384a6c88de33e",
		  "name":"2.3",
		  "description":"minor interface update"
	   }
	]
}

 

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.

 

Localtab Group
verticaltrue
Localtab
activetrue
titleREST
Excerpt Include
API REST Tip
API REST Tip
nopaneltrue

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

Excerpt Include
API HTTP Response - Update
API HTTP Response - Update
nopaneltrue


3. Examples

Localtab Group
Localtab
titlejson
Code Block
languagejs
titleRequest
PUT /v1/things/de629f2d3ecf4e7097be533dc88c18c8/versions/31370dd83fa249529722bd86dddb1bf6/switch.json
Code Block
languagejs
titleResponse
204 No Content
Localtab
titleMessaging
Excerpt Include
API MAPI Outdated
API MAPI Outdated
nopaneltrue
Excerpt Include
API Messaging Tip
API Messaging Tip
nopaneltrue

1. Request

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier established by the client 

thingId

xstring-

Identifier of a thing.

versionIdxstring-Version Id to switch/update to.
Code Block
{
	"jsonrpc":"2.0",
	"id":<request_id>,
	"method":"things.versions.switch",
	"params": {
		"thingId":<thing_id>,
		"versionId":<version_id>
	}
}

 

2. Response

AttributeRequiredTypeDefaultDescription
id stringnullRequest identifier specified in request
Code Block
languagejs
{
	"jsonrpc":"2.0",
	"id":<request_id>
}

3. Example

Localtab Group
Localtab
titlemqtt

Excerpt Include
API Mosquitto
API Mosquitto
nopaneltrue

Code Block
languagepowershell
mosquitto_pub -d -h api.gadgetkeeper.com -t "v1.f628d91dbda2499eb70cd9ac1a1ad50d.json" -m "{\"jsonrpc\":\"2.0\",\"id\":\"7755\",\"method\":\"things.versions.switch\",\"params\":{\"thingId\":\"de629f2d3ecf4e7097be533dc88c18c8\",\"versionId\":\"31370dd83fa249529722bd86dddb1bf6\"}}" 
Code Block
languagejs
titleRequest
{
    "jsonrpc":"2.0",
    "id":"7755",
    "method":"things.versions.switch",
    "params": {
        "thingId":"de629f2d3ecf4e7097be533dc88c18c8",
        "versionId":"31370dd83fa249529722bd86dddb1bf6"
    }
}
Code Block
languagejs
titleResponse
{
	"jsonrpc":"2.0",
	"id":"7755"
}