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

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, data volume restriction applies or quota limit exceeded.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

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

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

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

Response (Status 200)

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

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

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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']

Response (Status 200)

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

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

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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

actionHistory

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

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

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

Response (Status 200)

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

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[]

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

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

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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

Response (Status 200)

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

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

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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

Response (Status 200)

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

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

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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

actionHistory

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

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

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[]

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

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

Response (Status 200)

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

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[]

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

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[]

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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

actionHistory

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

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

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

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

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

© Bosch.IO GmbH, all rights reserved Corporate information | Data protection notice | Legal information | Support | Free plans