hawkBit rest docs (management & DDI API) (#688)
* hawkBit REST docs. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Fiy gitignore. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Add to website. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Switch to generated docs. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Fix typos. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Review findings. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Otimizations. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Revert accidental checkin. Signed-off-by: kaizimmerm <kai.zimmermann@bosch-si.com> * Add security link.
This commit is contained in:
Kai Zimmermann
@@ -12,6 +12,7 @@ The _hawkbit_ [update server](https://github.com/eclipse/hawkbit) provides REST
|
||||
Note: in DDI the target is identified using a **controllerId**. Controller is used as a term for the actual service/client on the device. That allows users to have in some cases even multiple clients on the same target for different tasks, e.g. Firmware update and App management.
|
||||
|
||||
# State Machine Mapping
|
||||
|
||||
For historical reasons the DDI has a different state machine and status messages than the [Target State Machine](../architecture/targetstate.html) of the _hawkBit_ update server.
|
||||
|
||||
This is kept in order to ensure that _DDI_ stays compatible for devices out there in the field. A future version "2" of _DDI_ might change that. _DDI_ also defines more states than the update server, e.g. multiple DDI states are currently mapped by the _DDI_ implementation to _RUNNING_ state. It is possible that in the future _hawkBit_ will fully leverage these additional states.
|
||||
@@ -28,147 +29,5 @@ SCHEDULED | This can be used by the target to inform that it s
|
||||
RESUMED | This can be used by the target to inform that it continued to work on the action. | RUNNING
|
||||
|
||||
# Resource Overview
|
||||
The following chapters provide basic examples for the most important resources but we provide also a [detailed resource documentation](https://docs.bosch-iot-rollouts.com/documentation/rest-api/rootcontroller-api-guide.html).
|
||||
|
||||
## Base Poll Resource
|
||||
|
||||
```
|
||||
GET /{tenant}/controller/v1/{controllerId}
|
||||
```
|
||||
|
||||
In the answer to the baseUrl polling the backend can send action links. A possible action is a deploy command. The client makes a GET request on the given link:
|
||||
|
||||
_Example Response_
|
||||
|
||||
```
|
||||
{
|
||||
"config": {
|
||||
"polling": {
|
||||
"sleep": "00:05:00"
|
||||
}
|
||||
},
|
||||
"_links": {
|
||||
"deploymentBase": {
|
||||
"href": "http://localhost:8080/default/controller/v1/example/deploymentBase/1?c=644088541"
|
||||
},
|
||||
"configData": {
|
||||
"href": "http://localhost:8080/default/controller/v1/example/configData"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment Base Resource
|
||||
|
||||
```
|
||||
GET /{tenant}/controller/v1/{controllerId}/deploymentBase/{id}
|
||||
```
|
||||
|
||||
_Example Response_
|
||||
|
||||
```
|
||||
{
|
||||
"deployment": {
|
||||
"download": "forced",
|
||||
"update": "forced",
|
||||
"chunks": [
|
||||
{
|
||||
"part": "os",
|
||||
"version": "1.0.0",
|
||||
"name": "Linux",
|
||||
"artifacts": [
|
||||
{
|
||||
"filename": "linux.zip",
|
||||
"hashes": {
|
||||
"sha1": "46fc56de883ec027759d8513458fe1010aa7e793",
|
||||
"md5": "5813e9655bd6871d0c25b8d510fd8605"
|
||||
},
|
||||
"size": 52167,
|
||||
"_links": {
|
||||
"download": {
|
||||
"href": "http://localhost:8080/default/controller/v1/example/softwaremodules/1/artifacts/linux.zip"
|
||||
},
|
||||
"md5sum": {
|
||||
"href": "http://localhost:8080/default/controller/v1/example/softwaremodules/1/artifacts/linux.zip.MD5SUM"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
"id": "1",
|
||||
"actionHistory": {
|
||||
"status": "RETRIEVED",
|
||||
"messages": [
|
||||
"Installing update",
|
||||
"Downloading artifacts"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment Feedback Resource
|
||||
To every deployment the client can post feedback back to the update-server about the deployment status.
|
||||
|
||||
```
|
||||
POST /{tenant}/controller/v1/{controllerId}/deploymentBase/{id}/feedback
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
_Example Body Deployment Success_
|
||||
|
||||
```
|
||||
{
|
||||
"id": 1,
|
||||
"time": "20140511T121314",
|
||||
"status": {
|
||||
"execution": "closed",
|
||||
"result": {
|
||||
"finished": "success",
|
||||
"progress": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
_Example Body Deployment Proceeding_
|
||||
|
||||
```
|
||||
{
|
||||
"id": "1",
|
||||
"time": "20140511T121314",
|
||||
"status": {
|
||||
"execution": "proceeding",
|
||||
"result": {
|
||||
"finished": "none",
|
||||
"progress": {
|
||||
"cnt": 2,
|
||||
"of": 5
|
||||
}
|
||||
},
|
||||
"details": [
|
||||
"checking hash sums"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
_Example Body Deployment Error_
|
||||
|
||||
```
|
||||
{
|
||||
"id": 1,
|
||||
"time": "20140511T121314",
|
||||
"status": {
|
||||
"execution": "rejected",
|
||||
"result": {
|
||||
"finished": "failure",
|
||||
"progress": {}
|
||||
},
|
||||
"details": [
|
||||
"something bad happend"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
<iframe src="../../rest-api/rootcontroller-api-guide.html"></iframe>
|
||||
Reference in New Issue
Block a user