- GET /{tenant}/controller/v1/{controllerid}
- GET /{tenant}/controller/v1/{controllerid}/cancelAction/{actionId}
- POST /{tenant}/controller/v1/{controllerid}/cancelAction/{actionId}/feedback
- PUT /{tenant}/controller/v1/{controllerid}/configData
- GET /{tenant}/controller/v1/{controllerid}/deploymentBase/{actionId}
- POST /{tenant}/controller/v1/{controllerid}/deploymentBase/{actionId}/feedback
- GET /{tenant}/controller/v1/{controllerid}/softwaremodules/{softwareModuleId}/artifacts
- Additional content
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 or open actions, 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://ddi-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
Host: ddi-api.host.com
Accept: application/hal+json
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.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;charset=UTF-8
Content-Length: 355
{
"config" : {
"polling" : {
"sleep" : "12:00:00"
}
},
"_links" : {
"deploymentBase" : {
"href" : "https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/84?c=-2054225397"
},
"configData" : {
"href" : "https://ddi-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 deployment operation |
|
_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;charset=UTF-8
Content-Length: 337
{
"config" : {
"polling" : {
"sleep" : "12:00:00"
}
},
"_links" : {
"cancelAction" : {
"href" : "https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/82"
},
"configData" : {
"href" : "https://ddi-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 SP server might cancel an operation, e.g. an unfinished update has a sucessor. It is up to the provisiong target to decide to accept the cancelation or reject it.
Cancel an action
Curl
$ curl 'https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/87' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/87 HTTP/1.1
Host: ddi-api.host.com
Accept: application/hal+json
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-Length: 63
Content-Type: application/hal+json;charset=UTF-8
{
"id" : "87",
"cancelAction" : {
"stopId" : "87"
}
}
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://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/90/feedback' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"id" : "90",
"time" : "20140511T121314",
"status" : {
"result" : {
"finished" : "success"
},
"execution" : "closed",
"details" : [ "Some feedback" ]
}
}'
Request URL
POST /TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/90/feedback HTTP/1.1
Content-Length: 184
Host: ddi-api.host.com
Content-Type: application/json;charset=UTF-8
{
"id" : "90",
"time" : "20140511T121314",
"status" : {
"result" : {
"finished" : "success"
},
"execution" : "closed",
"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 |
String |
id of the action |
||
time |
String |
time on the target device |
||
status |
Object |
target action status |
X |
|
status.execution |
enum |
status of the action execution |
['closed', 'proceeding', '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 resgisters 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://ddi-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"
},
"id" : "",
"time" : "20140511T121314",
"status" : {
"result" : {
"finished" : "success"
},
"execution" : "closed",
"details" : [ ]
}
}'
Request URL
PUT /TENANT_ID/controller/v1/CONTROLLER_ID/configData HTTP/1.1
Host: ddi-api.host.com
Content-Length: 260
Content-Type: application/json;charset=UTF-8
{
"mode" : "merge",
"data" : {
"VIN" : "JH4TB2H26CC000000",
"hwRevision" : "2"
},
"id" : "",
"time" : "20140511T121314",
"status" : {
"result" : {
"finished" : "success"
},
"execution" : "closed",
"details" : [ ]
}
}
Request path parameter
Parameter | Description |
---|---|
tenant |
The tenant |
controllerId |
id of the controller |
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
id |
String |
id of the action |
||
time |
String |
time on the target device |
||
status |
Object |
target action status |
X |
|
status.execution |
enum |
status of the action execution |
['closed', 'proceeding', '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 |
||
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://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/85?actionHistory=10' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/85?actionHistory=10 HTTP/1.1
Host: ddi-api.host.com
Accept: application/hal+json
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. |
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;charset=UTF-8
Content-Length: 7203
{
"id" : "85",
"deployment" : {
"download" : "forced",
"update" : "forced",
"maintenanceWindow" : "available",
"chunks" : [ {
"part" : "bApp",
"version" : "1.0.84",
"name" : "oneapplication",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "5c74de49835c1c33b3f53023d6cde111d11d7366",
"md5" : "032b8d8fe93b9dd73e21b71038e8c590",
"sha256" : "56201a455531a0acc90fe5666d25e3b09a9bf95e419a8aa2f41d74ce1e2e2c1d"
},
"size" : 12,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "5c74de49835c1c33b3f53023d6cde111d11d7366",
"md5" : "032b8d8fe93b9dd73e21b71038e8c590",
"sha256" : "56201a455531a0acc90fe5666d25e3b09a9bf95e419a8aa2f41d74ce1e2e2c1d"
},
"size" : 12,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/311/filename/file.signature.MD5SUM"
}
}
} ]
}, {
"part" : "jvm",
"version" : "1.0.3",
"name" : "oneapp runtime",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "1f32153e216d920f9d64f1ccb0fa9d9b6d78afae",
"md5" : "d98058461fcbd731aa294b5823353454",
"sha256" : "c732ca39001c48f1f7c0b17e0bcf3536a98f36d8cc57af25937afaa9fdcc135c"
},
"size" : 11,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "1f32153e216d920f9d64f1ccb0fa9d9b6d78afae",
"md5" : "d98058461fcbd731aa294b5823353454",
"sha256" : "c732ca39001c48f1f7c0b17e0bcf3536a98f36d8cc57af25937afaa9fdcc135c"
},
"size" : 11,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/312/filename/file.signature.MD5SUM"
}
}
} ],
"metadata" : [ {
"key" : "aMetadataKey",
"value" : "Metadata value as defined in software module"
} ]
}, {
"part" : "os",
"version" : "1.0.20",
"name" : "one Firmware",
"artifacts" : [ {
"filename" : "binary.tgz",
"hashes" : {
"sha1" : "5fcb2fcef539ba21b8583862f63bca902176cb1a",
"md5" : "19ae3ecf79b18a9541457d0e01233134",
"sha256" : "c0952a23bb4af93104c1b5e34ea445b78951c01800066084338be284dd870fc9"
},
"size" : 11,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/binary.tgz"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/binary.tgz"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/binary.tgz.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/binary.tgz.MD5SUM"
}
}
}, {
"filename" : "file.signature",
"hashes" : {
"sha1" : "5fcb2fcef539ba21b8583862f63bca902176cb1a",
"md5" : "19ae3ecf79b18a9541457d0e01233134",
"sha256" : "c0952a23bb4af93104c1b5e34ea445b78951c01800066084338be284dd870fc9"
},
"size" : 11,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/file.signature"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/file.signature"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/file.signature.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/313/filename/file.signature.MD5SUM"
}
}
} ]
} ]
},
"actionHistory" : {
"status" : "RUNNING",
"messages" : [ "Reboot", "Write firmware", "Download done", "Download failed. ErrorCode #5876745. Retry", "Started download" ]
}
}
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-Length: 495
Content-Type: application/hal+json;charset=UTF-8
{
"id" : "88",
"deployment" : {
"download" : "forced",
"update" : "skip",
"maintenanceWindow" : "unavailable",
"chunks" : [ {
"part" : "bApp",
"version" : "1.0.9",
"name" : "oneapplication",
"artifacts" : [ ]
}, {
"part" : "jvm",
"version" : "1.0.20",
"name" : "oneapp runtime",
"artifacts" : [ ]
}, {
"part" : "os",
"version" : "1.0.74",
"name" : "one Firmware",
"artifacts" : [ ]
} ]
}
}
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://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/86/feedback' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Accept: application/hal+json' \
-d '{
"id" : "86",
"time" : "20140511T121314",
"status" : {
"result" : {
"progress" : {
"of" : 5,
"cnt" : 2
},
"finished" : "none"
},
"execution" : "closed",
"details" : [ "Feddback message" ]
}
}'
Request URL
POST /TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/86/feedback HTTP/1.1
Content-Length: 250
Host: ddi-api.host.com
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json
{
"id" : "86",
"time" : "20140511T121314",
"status" : {
"result" : {
"progress" : {
"of" : 5,
"cnt" : 2
},
"finished" : "none"
},
"execution" : "closed",
"details" : [ "Feddback 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 |
String |
id of the action |
||
time |
String |
time on the target device |
||
status |
Object |
target action status |
X |
|
status.execution |
enum |
status of the action execution |
['closed', 'proceeding', '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 |
||
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. |
GET /{tenant}/controller/v1/{controllerid}/softwaremodules/{softwareModuleId}/artifacts
Implementation notes
Returns all artifacts whichs is assigned to the software module
Returns artifacts of given software module
Curl
$ curl 'https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/softwaremodules/323/artifacts' -i -X GET \
-H 'Accept: application/hal+json'
Request URL
GET /TENANT_ID/controller/v1/CONTROLLER_ID/softwaremodules/323/artifacts HTTP/1.1
Host: ddi-api.host.com
Accept: application/hal+json
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-Length: 926
Content-Type: application/hal+json;charset=UTF-8
[ {
"filename" : "binaryFile",
"hashes" : {
"sha1" : "d4f62413897d7760e680377fd8987439191c0969",
"md5" : "a5861dc581c335b5bd0686b66e3d8e29",
"sha256" : "1e4438fdd390feb24a837bc6d25b29d398520110c03a9c4107372f1e63563d21"
},
"size" : 11,
"_links" : {
"download" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/323/filename/binaryFile"
},
"download-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/323/filename/binaryFile"
},
"md5sum-http" : {
"href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/323/filename/binaryFile.MD5SUM"
},
"md5sum" : {
"href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/323/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 |