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>
|
||||
@@ -8,6 +8,7 @@ title: Management-API
|
||||
# Management API
|
||||
|
||||
## Overview
|
||||
|
||||
The Management API is a RESTful API that enables to perform Create/Read/Update/Delete operations for provisioning targets (i.e. devices) and repository content (i.e. software). Based on the Management API you can manage and monitor software update operations via HTTP/HTTPS. The _Management API_ supports JSON payload with hypermedia as well as filtering, sorting and paging. Furthermore the Management API provides permission based access control and standard roles as well as custom role creation.
|
||||
|
||||
The API is protected and needs authentication and authorization based on the security concept.
|
||||
@@ -29,15 +30,16 @@ Supported HTTP-methods are:
|
||||
|
||||
Available Management APIs resources are:
|
||||
|
||||
* [Targets](https://docs.bosch-iot-rollouts.com/documentation/rest-api/targets-api-guide.html)
|
||||
* [Distribution Sets](https://docs.bosch-iot-rollouts.com/documentation/rest-api/distributionsets-api-guide.html)
|
||||
* [Distribution Set Types](https://docs.bosch-iot-rollouts.com/documentation/rest-api/distributionsettypes-api-guide.html)
|
||||
* [Software Modules](https://docs.bosch-iot-rollouts.com/documentation/rest-api/softwaremodules-api-guide.html)
|
||||
* [Software Module Types](https://docs.bosch-iot-rollouts.com/documentation/rest-api/softwaremoduletypes-api-guide.html)
|
||||
* [Target Tag](https://docs.bosch-iot-rollouts.com/documentation/rest-api/targettag-api-guide.html)
|
||||
* [Distribution Set Tag](https://docs.bosch-iot-rollouts.com/documentation/rest-api/distributionsettag-api-guide.html)
|
||||
* [Rollouts](https://docs.bosch-iot-rollouts.com/documentation/rest-api/rollout-api-guide.html)
|
||||
* [System Configuration](https://docs.bosch-iot-rollouts.com/documentation/rest-api/tenant-api-guide.html)
|
||||
- [Targets](managementapi/targets.html)
|
||||
- [Distribution sets](managementapi/distributionsets.html)
|
||||
- [Distribution set types](managementapi/distributionsettypes.html)
|
||||
- [Software modules](managementapi/softwaremodules.html)
|
||||
- [Software module types](managementapi/softwaremoduletypes.html)
|
||||
- [Target tag](managementapi/targettag.html)
|
||||
- [Distribution set tag](managementapi/distributionsettag.html)
|
||||
- [Rollouts](managementapi/rollouts.html)
|
||||
- [Target filters](managementapi/targetfilters.html)
|
||||
- [System configuration](managementapi/tenant.html)
|
||||
|
||||
|
||||
## Headers
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/distributionsets-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/distributionsettag-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,7 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
|
||||
<iframe src="../../rest-api/distributionsettypes-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/rollout-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/softwaremodules-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/softwaremoduletypes-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/targetfilters-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/targets-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/targettag-api-guide.html"></iframe>
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
layout: documentation
|
||||
title: Management-API
|
||||
---
|
||||
|
||||
<iframe src="../../rest-api/tenant-api-guide.html"></iframe>
|
||||
Reference in New Issue
Block a user