GET /{tenant}/controller/v1/{controllerid}
Implementation notes
This base resource can be regularly polled by the controller on the provisioning target or device in order to retrieve actions that need to be executed. Those are provided as a list of links to give more detailed information about the action. Links are only available for initial configuration, open actions, or the latest installed action, respectively. The resource supports Etag based modification checks in order to save traffic.
Note: deployments have to be confirmed in order to move on to the next action. Cancellations have to be confirmed or rejected.
Controller base poll resource
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
Response (Status 200) with an active deployment
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
config.polling |
Object |
suggested sleep time between polls |
|
config.polling.sleep |
String |
sleep time in HH:MM:SS notation |
|
_links |
Object |
Open Actions that the server has for the target |
|
_links.deploymentBase |
Object |
Detailed deployment operation |
|
_links.installedBase |
Object |
Detailed operation of last successfully finished action |
|
_links.configData |
Object |
Link which is provided whenever the provisioning target or device is supposed to push its configuration data (aka. "controller attributes") to the server. Only shown for the initial configuration, after a successful update action, or if requested explicitly (e.g. via the management UI). |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 502
{
"config" : {
"polling" : {
"sleep" : "12:00:00"
}
},
"_links" : {
"deploymentBase" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/5?c=-2127183556"
},
"installedBase" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/installedBase/4"
},
"configData" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/configData"
}
}
}
Response (Status 200) with an active cancellation
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
config.polling |
Object |
suggested sleep time between polls |
|
config.polling.sleep |
String |
sleep time in HH:MM:SS notation |
|
_links |
Object |
Open Actions that the server has for the target |
|
_links.cancelAction |
Object |
Detailed cancel operation of a deployment |
|
_links.installedBase |
Object |
Detailed operation of last successfully finished action |
|
_links.configData |
Object |
Link which is provided whenever the provisioning target or device is supposed to push its configuration data (aka. "controller attributes") to the server. Only shown for the initial configuration, after a successful update action, or if requested explicitly (e.g. via the management UI). |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 484
{
"config" : {
"polling" : {
"sleep" : "12:00:00"
}
},
"_links" : {
"cancelAction" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/2"
},
"installedBase" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/installedBase/1"
},
"configData" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/configData"
}
}
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, data volume restriction applies or quota limit exceeded. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /{tenant}/controller/v1/{controllerid}/cancelAction/{actionId}
Implementation notes
The Bosch IoT Rollouts server might cancel an operation, e.g. an unfinished update has a successor. It is up to the provisioning target to decide to accept the cancelation or reject it.
Cancel an action
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/11' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/11 HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
actionId |
id of the action that needs to be canceled (typically identical to id field on the cancel action itself) |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
id |
String |
id of the action |
|
cancelAction |
Object |
action that needs to be canceled |
|
cancelAction.stopId |
String |
id of the action that needs to be canceled (typically identical to id field on the cancel action itself) |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 63
{
"id" : "11",
"cancelAction" : {
"stopId" : "11"
}
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /{tenant}/controller/v1/{controllerid}/cancelAction/{actionId}/feedback
Implementation notes
It is up to the device how much intermediate feedback is provided. However, the action will be kept open until the controller on the device reports a finished (either successful or error) or rejects the action, e.g. the canceled actions have been started already.
Feedback channel for cancel actions
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/16/feedback' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"time" : "2023-02-17T08:56:32.494207Z",
"status" : {
"execution" : "closed",
"result" : {
"finished" : "success",
"progress" : {
"cnt" : 2,
"of" : 5
}
},
"code" : null,
"details" : [ "Some feedback" ]
}
}'
Request URL
POST /TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/16/feedback HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 266
Host: management-api.host.com
{
"time" : "2023-02-17T08:56:32.494207Z",
"status" : {
"execution" : "closed",
"result" : {
"finished" : "success",
"progress" : {
"cnt" : 2,
"of" : 5
}
},
"code" : null,
"details" : [ "Some feedback" ]
}
}
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
actionId |
id of the action that needs to be canceled (typically identical to id field on the cancel action itself) |
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
id |
Number |
(@deprecated) id of the action |
||
time |
String |
timestamp of the action |
||
status |
Object |
target action status |
X |
|
status.code |
Null |
optional individual status code |
X |
|
status.execution |
enum |
status of the action execution |
['closed', 'proceeding', 'download', 'downloaded', 'canceled','scheduled', 'rejected', 'resumed'] |
X |
status.result |
Object |
result of the action execution |
X |
|
status.result.finished |
enum |
defined status of the result |
['success', 'failure', 'none'] |
X |
status.details |
Array |
List of details message information |
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request. |
See Error body |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
PUT /{tenant}/controller/v1/{controllerid}/configData
Implementation notes
The usual behaviour is that when a new device registers at the server it is requested to provide the meta information that will allow the server to identify the device on a hardware level (e.g. hardware revision, mac address, serial number etc.).
Response to a requested metadata pull from the provisioning target device.
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/configData' -i -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"mode" : "merge",
"data" : {
"VIN" : "JH4TB2H26CC000000",
"hwRevision" : "2"
}
}'
Request URL
PUT /TENANT_ID/controller/v1/CONTROLLER_ID/configData HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 96
Host: management-api.host.com
{
"mode" : "merge",
"data" : {
"VIN" : "JH4TB2H26CC000000",
"hwRevision" : "2"
}
}
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
data |
Object |
Link which is provided whenever the provisioning target or device is supposed to push its configuration data (aka. "controller attributes") to the server. Only shown for the initial configuration, after a successful update action, or if requested explicitly (e.g. via the management UI). |
X |
|
mode |
enum |
Optional parameter to specify the update mode that should be applied when updating target attributes. Valid values are 'merge', 'replace', and 'remove'. Defaults to 'merge'. |
['merge', 'replace', 'remove'] |
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request. |
See Error body |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /{tenant}/controller/v1/{controllerid}/deploymentBase/{actionId}
Implementation notes
Core resource for deployment operations. Contains all information necessary in order to execute the operation.
Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. Host, port and path and not guaranteed to be similar to the provided examples below but will be defined at runtime.
Deployment or update action
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/8?actionHistory=10' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/8?actionHistory=10 HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
actionId |
id of the action |
Request query parameter
Parameter | Description |
---|---|
|
Optional GET parameter to retrieve a given number of messages which are previously provided by the device. Useful if the devices sent state information to the feedback channel and never stored them locally. |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
id |
String |
id of the action |
|
deployment |
Object |
Detailed deployment operation |
|
deployment.download |
enum |
handling for the download part of the provisioning process ('skip': do not download yet, 'attempt': server asks to download, 'forced': server requests immediate download) |
['skip', 'attempt', 'forced'] |
deployment.update |
enum |
handling for the update part of the provisioning process ('skip': do not update yet, 'attempt': server asks to update, 'forced': server requests immediate update) |
['skip', 'attempt', 'forced'] |
deployment.maintenanceWindow |
enum |
separation of download and installation by defining a maintenance window for the installation. Status shows if currently in a window. |
['available', 'unavailable'] |
deployment.chunks |
Array |
Software chunks of an update. In server mapped by Software Module. |
|
deployment.chunks[].metadata |
Array |
meta data of the respective software module that has been marked with 'target visible' |
|
deployment.chunks[].metadata[].key |
String |
key of meta data entry |
|
deployment.chunks[].metadata[].value |
String |
value of meta data entry |
|
deployment.chunks[].part |
String |
Type of the chunk, e.g. firmware, bundle, app. In update server mapped to Software Module Type. |
|
deployment.chunks[].name |
String |
name of the chunk |
|
deployment.chunks[].version |
String |
software version of the chunk |
|
deployment.chunks[].artifacts |
Array |
list of artifacts |
|
deployment.chunks[].artifacts[].filename |
String |
list of artifacts |
|
deployment.chunks[].artifacts[].hashes |
Object |
list of artifacts |
|
deployment.chunks[].artifacts[].hashes.sha1 |
String |
SHA1 hash of the artifact in Base 16 format |
|
deployment.chunks[].artifacts[].hashes.md5 |
String |
MD5 hash of the artifact |
|
deployment.chunks[].artifacts[].hashes.sha256 |
String |
SHA-256 hash of the artifact in Base 16 format |
|
deployment.chunks[].artifacts[].size |
Number |
size of the artifact |
|
deployment.chunks[].artifacts[]._links.download |
Object |
HTTPs Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. |
|
deployment.chunks[].artifacts[]._links.md5sum |
Object |
HTTPs Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. |
|
deployment.chunks[].artifacts[]._links.download-http |
Object |
HTTP Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
|
deployment.chunks[].artifacts[]._links.md5sum-http |
Object |
HTTP Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
|
actionHistory |
Object |
Current deployment state. |
|
actionHistory.status |
String |
Status of the deployment based on previous feedback by the device. |
|
actionHistory.messages |
Array |
Messages are previously sent to the feedback channel in LIFO order by the device. Note: The first status message is set by the system and describes the trigger of the deployment |
Response example
In this case the (optional) query for the last 10 messages, previously provided by the device, are included. Useful if the devices provide state information previously on the feedback channel and won’t store it locally.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 7220
{
"id" : "8",
"deployment" : {
"download" : "forced",
"update" : "forced",
"maintenanceWindow" : "available",
"chunks" : [ {
"part" : "jvm",
"version" : "1.0.66",
"name" : "oneapp runtime",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/23/filename/file.signature.MD5SUM"
}
}
} ]
}, {
"part" : "os",
"version" : "1.0.8",
"name" : "one Firmware",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/24/filename/file.signature.MD5SUM"
}
}
} ]
}, {
"part" : "bApp",
"version" : "1.0.59",
"name" : "oneapplication",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "3b93fd2d045d59af27a25c719945db1d9fe3decb",
"md5" : "e94f0bfab8c987a7437ba4e1697c1cc0",
"sha256" : "5d04c6a96439100ad3cb4672ef2fdc219dae8aaa655c9a3095c9e7ad25f4d96c"
},
"size" : 4,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "3b93fd2d045d59af27a25c719945db1d9fe3decb",
"md5" : "e94f0bfab8c987a7437ba4e1697c1cc0",
"sha256" : "5d04c6a96439100ad3cb4672ef2fdc219dae8aaa655c9a3095c9e7ad25f4d96c"
},
"size" : 4,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/file.signature.MD5SUM"
}
}
} ],
"metadata" : [ {
"key" : "aMetadataKey",
"value" : "Metadata value as defined in software module"
} ]
} ]
},
"actionHistory" : {
"status" : "RUNNING",
"messages" : [ "Reboot", "Write firmware", "Download done", "Download failed. ErrorCode #5876745. Retry", "Started download", "Assignment initiated by user 'TestPrincipal'" ]
}
}
Response (Status 200) with a maintenance window defined but not active yet
In addition to the straight forward approach to inform the device to download and install the software in one transaction hawkBit supports the separation of download and installation into separate steps.
This feature is called Maintenance Window where the device is informed to download the software first and then when it enters a defined (maintenance) window the installation triggers follows as in the example above.
Response example
Note: artifact details not shown in this example.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 615
{
"id" : "12",
"deployment" : {
"download" : "forced",
"update" : "skip",
"maintenanceWindow" : "unavailable",
"chunks" : [ {
"part" : "bApp",
"version" : "1.0.7",
"name" : "oneapplication",
"artifacts" : [ ]
}, {
"part" : "jvm",
"version" : "1.0.12",
"name" : "oneapp runtime",
"artifacts" : [ ]
}, {
"part" : "os",
"version" : "1.0.7",
"name" : "one Firmware",
"artifacts" : [ ]
} ]
},
"actionHistory" : {
"status" : "RUNNING",
"messages" : [ "Assignment initiated by user 'TestPrincipal'" ]
}
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /{tenant}/controller/v1/{controllerid}/deploymentBase/{actionId}/feedback
Implementation notes
Feedback channel. It is up to the device how much intermediate feedback is provided. However, the action will be kept open until the controller on the device reports a finished (either successful or error).
Feedback channel for update action
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/9/feedback' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/hal+json' \
-d '{
"time" : "2023-02-17T08:56:23.791568Z",
"status" : {
"execution" : "closed",
"result" : {
"finished" : "success",
"progress" : {
"cnt" : 2,
"of" : 5
}
},
"code" : 200,
"details" : [ "Feedback message" ]
}
}'
Request URL
POST /TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/9/feedback HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json
Content-Length: 268
Host: management-api.host.com
{
"time" : "2023-02-17T08:56:23.791568Z",
"status" : {
"execution" : "closed",
"result" : {
"finished" : "success",
"progress" : {
"cnt" : 2,
"of" : 5
}
},
"code" : 200,
"details" : [ "Feedback message" ]
}
}
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
actionId |
id of the action |
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
id |
Number |
(@deprecated) id of the action |
||
time |
String |
timestamp of the action |
||
status |
Object |
target action status |
X |
|
status.code |
Number |
optional individual status code |
X |
|
status.execution |
enum |
status of the action execution |
['closed', 'proceeding', 'download', 'downloaded', 'canceled','scheduled', 'rejected', 'resumed'] |
X |
status.result |
Object |
result of the action execution |
X |
|
status.result.finished |
enum |
defined status of the result |
['success', 'failure', 'none'] |
X |
status.result.progress |
Object |
progress assumption of the device (currently not supported). |
||
status.details |
Array |
List of details message information |
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request. |
See Error body Unresolved directive in rootcontroller-api-guide.adoc - include::../errors/410.adoc[] |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /{tenant}/controller/v1/{controllerid}/confirmationBase
Implementation notes
Core resource for confirmation related operations. While active actions awaiting confirmation will be referenced, the current auto-confirmation status will be shown. In case auto-confirmation is active, details like the initiator, remark and date of activation (as unix timestamp) will be provided. Reference links to switch the auto-confirmation state are exposed as well.
Resource to request confirmation specific information for the controller
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
Response example (auto-confirmation is active)
The response body in case auto-confirmation is active.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 333
{
"autoConfirm" : {
"active" : true,
"initiator" : "exampleUserId",
"remark" : "exampleRemark",
"activatedAt" : 1676624181646
},
"_links" : {
"deactivateAutoConfirm" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/deactivateAutoConfirm"
}
}
}
Response example (auto-confirmation is not active)
The response body references a link to activate auto-confirmation as well as a link to an open action waiting for confirmation (if present).
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 383
{
"autoConfirm" : {
"active" : false
},
"_links" : {
"activateAutoConfirm" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/activateAutoConfirm"
},
"confirmationBase" : {
"href" : "https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/10?c=-2122565939"
}
}
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request. |
See Error body |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /{tenant}/controller/v1/{controllerid}/confirmationBase/activateAutoConfirm
Implementation notes
The device can use this resource to activate auto-confirmation. As a result all current active as well as future actions will automatically be confirmed by mentioning the initiator as triggered person. Actions will be automatically confirmed, as long as auto-confirmation is active.
Interface to activate auto-confirmation for a specific device
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/activateAutoConfirm' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"initiator" : "exampleUser",
"remark" : "exampleRemark"
}'
Request URL
POST /TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/activateAutoConfirm HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 63
Host: management-api.host.com
{
"initiator" : "exampleUser",
"remark" : "exampleRemark"
}
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
initiator |
String |
individual value (e.g. username) stored as initiator and automatically used as confirmed user in future actions |
||
remark |
String |
individual value to attach a remark which will be persisted when automatically confirming future actions |
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request. |
See Error body |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /{tenant}/controller/v1/{controllerid}/confirmationBase/deactivateAutoConfirm
Implementation notes
The device can use this resource to deactivate auto-confirmation. All active actions will remain unchanged while all future actions need to be confirmed, before processing with the deployment.
Interface to deactivate auto-confirmation for a specific controller
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/deactivateAutoConfirm' -i -X POST
Request URL
POST /TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/deactivateAutoConfirm HTTP/1.1
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request. |
See Error body |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /{tenant}/controller/v1/{controllerid}/confirmationBase/{actionId}
Implementation notes
Resource to receive information about a pending confirmation. The response will be of the same format as the deploymentBase operation. The controller should provide feedback about the confirmation first, before processing the deployment.
Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. Host, port and path are not guaranteed to be similar to the provided examples below but will be defined at runtime.
Confirmation status of an action
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/6?actionHistory=10' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/6?actionHistory=10 HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
actionId |
id of the action |
Request query parameter
Parameter | Description |
---|---|
|
Optional GET parameter to retrieve a given number of messages which are previously provided by the device. Useful if the devices sent state information to the feedback channel and never stored them locally. |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
id |
String |
id of the action |
|
confirmation |
Object |
Deployment confirmation operation |
|
confirmation.download |
enum |
handling for the download part of the provisioning process ('skip': do not download yet, 'attempt': server asks to download, 'forced': server requests immediate download) |
['skip', 'attempt', 'forced'] |
confirmation.update |
enum |
handling for the update part of the provisioning process ('skip': do not update yet, 'attempt': server asks to update, 'forced': server requests immediate update) |
['skip', 'attempt', 'forced'] |
confirmation.maintenanceWindow |
enum |
separation of download and installation by defining a maintenance window for the installation. Status shows if currently in a window. |
['available', 'unavailable'] |
confirmation.chunks |
Array |
Software chunks of an update. In server mapped by Software Module. |
|
confirmation.chunks[].metadata |
Array |
meta data of the respective software module that has been marked with 'target visible' |
|
confirmation.chunks[].metadata[].key |
String |
key of meta data entry |
|
confirmation.chunks[].metadata[].value |
String |
value of meta data entry |
|
confirmation.chunks[].part |
String |
Type of the chunk, e.g. firmware, bundle, app. In update server mapped to Software Module Type. |
|
confirmation.chunks[].name |
String |
name of the chunk |
|
confirmation.chunks[].version |
String |
software version of the chunk |
|
confirmation.chunks[].artifacts |
Array |
list of artifacts |
|
confirmation.chunks[].artifacts[].filename |
String |
list of artifacts |
|
confirmation.chunks[].artifacts[].hashes |
Object |
list of artifacts |
|
confirmation.chunks[].artifacts[].hashes.sha1 |
String |
SHA1 hash of the artifact in Base 16 format |
|
confirmation.chunks[].artifacts[].hashes.md5 |
String |
MD5 hash of the artifact |
|
confirmation.chunks[].artifacts[].hashes.sha256 |
String |
SHA-256 hash of the artifact in Base 16 format |
|
confirmation.chunks[].artifacts[].size |
Number |
size of the artifact |
|
confirmation.chunks[].artifacts[]._links.download |
Object |
HTTPs Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. |
|
confirmation.chunks[].artifacts[]._links.md5sum |
Object |
HTTPs Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. |
|
confirmation.chunks[].artifacts[]._links.download-http |
Object |
HTTP Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
|
confirmation.chunks[].artifacts[]._links.md5sum-http |
Object |
HTTP Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
|
actionHistory |
Object |
Current deployment state. |
|
actionHistory.status |
String |
Status of the deployment based on previous feedback by the device. |
|
actionHistory.messages |
Array |
Messages are previously sent to the feedback channel in LIFO order by the device. Note: The first status message is set by the system and describes the trigger of the deployment |
Response example
The response body includes the detailed information about the action awaiting confirmation in the same format as for the deploymentBase operation.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 7210
{
"id" : "6",
"confirmation" : {
"download" : "forced",
"update" : "forced",
"maintenanceWindow" : "available",
"chunks" : [ {
"part" : "bApp",
"version" : "1.0.66",
"name" : "oneapplication",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/16/filename/file.signature.MD5SUM"
}
}
} ]
}, {
"part" : "jvm",
"version" : "1.0.14",
"name" : "oneapp runtime",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/17/filename/file.signature.MD5SUM"
}
}
} ],
"metadata" : [ {
"key" : "aMetadataKey",
"value" : "Metadata value as defined in software module"
} ]
}, {
"part" : "os",
"version" : "1.0.45",
"name" : "one Firmware",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/18/filename/file.signature.MD5SUM"
}
}
} ]
} ]
},
"actionHistory" : {
"status" : "WAIT_FOR_CONFIRMATION",
"messages" : [ "Assignment initiated by user 'TestPrincipal'", "Waiting for the confirmation by the device before processing with the deployment" ]
}
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body Unresolved directive in rootcontroller-api-guide.adoc - include::../errors/404_target_action.adoc[] |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /{tenant}/controller/v1/{controllerid}/confirmationBase/{actionId}/feedback
Implementation notes
The device will use this resource to either confirm or deny an action which is waiting for confirmation. The action will be transferred into the RUNNING state in case the device is confirming it. Afterwards it will be exposed by the deploymentBase.
Feedback channel for actions waiting for confirmation
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/13/feedback' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/hal+json' \
-d '{
"confirmation" : "confirmed",
"code" : 33,
"details" : [ "Feedback message" ]
}'
Request URL
POST /TENANT_ID/controller/v1/CONTROLLER_ID/confirmationBase/13/feedback HTTP/1.1
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json
Content-Length: 87
Host: management-api.host.com
{
"confirmation" : "confirmed",
"code" : 33,
"details" : [ "Feedback message" ]
}
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
actionId |
id of the action |
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
confirmation |
enum |
action confirmation state |
['confirmed', 'denied'] |
X |
code |
Number |
optional individual status code |
||
details |
Array |
List of detailed message information |
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body Unresolved directive in rootcontroller-api-guide.adoc - include::../errors/404_target_action.adoc[] |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request. |
See Error body Unresolved directive in rootcontroller-api-guide.adoc - include::../errors/410.adoc[] |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /{tenant}/controller/v1/{controllerid}/installedBase/{actionId}
Implementation notes
Resource to receive information of the previous installation. Can be used to re-retrieve artifacts of the already finished action, for example in case a re-installation is necessary. The response will be of the same format as the deploymentBase operation, providing the previous action that has been finished successfully. As the action is already finished, no further feedback is expected.
Keep in mind that the provided download links for the artifacts are generated dynamically by the update server. Host, port and path are not guaranteed to be similar to the provided examples below but will be defined at runtime.
Previously installed action
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/installedBase/15?actionHistory=10' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/installedBase/15?actionHistory=10 HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
actionId |
id of the action |
Request query parameter
Parameter | Description |
---|---|
|
Optional GET parameter to retrieve a given number of messages which are previously provided by the device. Useful if the devices sent state information to the feedback channel and never stored them locally. |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
id |
String |
id of the action |
|
deployment |
Object |
Detailed deployment operation |
|
deployment.download |
enum |
handling for the download part of the provisioning process ('skip': do not download yet, 'attempt': server asks to download, 'forced': server requests immediate download) |
['skip', 'attempt', 'forced'] |
deployment.update |
enum |
handling for the update part of the provisioning process ('skip': do not update yet, 'attempt': server asks to update, 'forced': server requests immediate update) |
['skip', 'attempt', 'forced'] |
deployment.maintenanceWindow |
enum |
separation of download and installation by defining a maintenance window for the installation. Status shows if currently in a window. |
['available', 'unavailable'] |
deployment.chunks |
Array |
Software chunks of an update. In server mapped by Software Module. |
|
deployment.chunks[].metadata |
Array |
meta data of the respective software module that has been marked with 'target visible' |
|
deployment.chunks[].metadata[].key |
String |
key of meta data entry |
|
deployment.chunks[].metadata[].value |
String |
value of meta data entry |
|
deployment.chunks[].part |
String |
Type of the chunk, e.g. firmware, bundle, app. In update server mapped to Software Module Type. |
|
deployment.chunks[].name |
String |
name of the chunk |
|
deployment.chunks[].version |
String |
software version of the chunk |
|
deployment.chunks[].artifacts |
Array |
list of artifacts |
|
deployment.chunks[].artifacts[].filename |
String |
list of artifacts |
|
deployment.chunks[].artifacts[].hashes |
Object |
list of artifacts |
|
deployment.chunks[].artifacts[].hashes.sha1 |
String |
SHA1 hash of the artifact in Base 16 format |
|
deployment.chunks[].artifacts[].hashes.md5 |
String |
MD5 hash of the artifact |
|
deployment.chunks[].artifacts[].hashes.sha256 |
String |
SHA-256 hash of the artifact in Base 16 format |
|
deployment.chunks[].artifacts[].size |
Number |
size of the artifact |
|
deployment.chunks[].artifacts[]._links.download |
Object |
HTTPs Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. |
|
deployment.chunks[].artifacts[]._links.md5sum |
Object |
HTTPs Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. |
|
deployment.chunks[].artifacts[]._links.download-http |
Object |
HTTP Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
|
deployment.chunks[].artifacts[]._links.md5sum-http |
Object |
HTTP Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
|
actionHistory |
Object |
Current deployment state. |
|
actionHistory.status |
String |
Status of the deployment based on previous feedback by the device. |
|
actionHistory.messages |
Array |
Messages are previously sent to the feedback channel in LIFO order by the device. Note: The first status message is set by the system and describes the trigger of the deployment |
Response example
The response body includes the detailed operation for the already finished action in the same format as for the deploymentBase operation.
In this case the (optional) query for the last 10 messages, previously provided by the device, are included.
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 7239
{
"id" : "15",
"deployment" : {
"download" : "forced",
"update" : "forced",
"maintenanceWindow" : "available",
"chunks" : [ {
"part" : "jvm",
"version" : "1.0.79",
"name" : "zeroapp runtime",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/44/filename/file.signature.MD5SUM"
}
}
} ]
}, {
"part" : "os",
"version" : "1.0.33",
"name" : "zero Firmware",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/45/filename/file.signature.MD5SUM"
}
}
} ]
}, {
"part" : "bApp",
"version" : "1.0.35",
"name" : "zeroapplication",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "3b93fd2d045d59af27a25c719945db1d9fe3decb",
"md5" : "e94f0bfab8c987a7437ba4e1697c1cc0",
"sha256" : "5d04c6a96439100ad3cb4672ef2fdc219dae8aaa655c9a3095c9e7ad25f4d96c"
},
"size" : 4,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "3b93fd2d045d59af27a25c719945db1d9fe3decb",
"md5" : "e94f0bfab8c987a7437ba4e1697c1cc0",
"sha256" : "5d04c6a96439100ad3cb4672ef2fdc219dae8aaa655c9a3095c9e7ad25f4d96c"
},
"size" : 4,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/43/filename/file.signature.MD5SUM"
}
}
} ],
"metadata" : [ {
"key" : "aMetadataKey",
"value" : "Metadata value as defined in software module"
} ]
} ]
},
"actionHistory" : {
"status" : "FINISHED",
"messages" : [ "Installed", "Reboot", "Write firmware", "Download done", "Download failed. ErrorCode #5876745. Retry", "Started download", "Assignment initiated by user 'TestPrincipal'" ]
}
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /{tenant}/controller/v1/{controllerid}/softwaremodules/{softwareModuleId}/artifacts
Implementation notes
Returns all artifacts that are assigned to the software module
Returns artifacts of given software module
Curl
$ curl 'https://management-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/softwaremodules/40/artifacts' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/softwaremodules/40/artifacts HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
moduleId |
id of the software module |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
[]filename |
String |
list of artifacts |
|
[]hashes |
Object |
list of artifacts |
|
[]hashes.sha1 |
String |
SHA1 hash of the artifact in Base 16 format |
|
[]hashes.md5 |
String |
MD5 hash of the artifact |
|
[]hashes.sha256 |
String |
SHA-256 hash of the artifact in Base 16 format |
|
[]size |
Number |
size of the artifact |
|
[]_links.download |
Object |
HTTPs Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. |
|
[]_links.md5sum |
Object |
HTTPs Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. |
|
[]_links.download-http |
Object |
HTTP Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
|
[]_links.md5sum-http |
Object |
HTTP Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. (note: anonymous download needs to be enabled on the service account for non-TLS access) |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 921
[ {
"filename" : "binaryFile",
"hashes" : {
"sha1" : "2d86c2a659e364e9abba49ea6ffcd53dd5559f05",
"md5" : "0d1b08c34858921bc7c662b228acb7ba",
"sha256" : "a03b221c6c6eae7122ca51695d456d5222e524889136394944b2f9763b483615"
},
"size" : 3,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/40/filename/binaryFile"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/40/filename/binaryFile"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/40/filename/binaryFile.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/40/filename/binaryFile.MD5SUM"
}
}
} ]
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
Additional content
Error body
{
"errorCode": "string",
"exceptionClass": "string",
"message": "string",
"parameters": [
"string"
]
}
Field description
Field |
Description |
errorCode |
A error code/key set by server |
exceptionClass |
The involved exceptionClass |
message |
An error message set by the server |
parameters |
A list of parameters |