API docs by Redocly

Direct Device Integration API (1.0)

Download OpenAPI specification:Download

Direct Device Integration API

DDI Root Controller

REST resource handling for root controller CRUD operations

Set offline assigned version

Allow to set current running version. This method is EXPERIMENTAL and may change in future releases.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
Request Body schema:
required
name
required
string

Distribution Set name

version
required
string

Distribution set version

Responses

Request samples

Content type
{
  • "name": "linux",
  • "version": "1.2.3"
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for the config data action

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.).

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
Request Body schema:
required
required
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).

mode
string
Enum: "merge" "replace" "remove"

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

Responses

Request samples

Content type
{
  • "mode": "merge",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for the DeploymentBase action

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).

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
Request Body schema:
required
time
string

Timestamp of the action

required
object (DdiStatus)

Target action status

Responses

Request samples

Content type
{
  • "time": "2023-08-03T12:31:41.890992967Z",
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for actions waiting for confirmation

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
Request Body schema:
required
confirmation
required
string
Enum: "confirmed" "denied"

Action confirmation state

code
integer <int32>

(Optional) Individual status code

details
Array of strings

List of detailed message information

Responses

Request samples

Content type
{
  • "confirmation": "confirmed",
  • "code": 200,
  • "details": [
    ]
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Interface to deactivate auto-confirmation for a specific controller

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Interface to activate auto-confirmation for a specific device

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
Request Body schema:
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

Responses

Request samples

Content type
{
  • "initiator": "exampleUser",
  • "remark": "exampleRemark"
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Feedback channel for cancel actions

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
Request Body schema:
required
time
string

Timestamp of the action

required
object (DdiStatus)

Target action status

Responses

Request samples

Content type
{
  • "time": "2023-08-03T12:31:41.890992967Z",
  • "status": {
    }
}

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Root resource for an individual Target

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string

Responses

Response samples

Content type
{}

Return all artifacts of a given software module and target

Returns all artifacts that are assigned to the software module

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
softwareModuleId
required
integer <int64>

Responses

Response samples

Content type
[]

Artifact download

Handles GET DdiArtifact download request. This could be full or partial (as specified by RFC7233 (Range Requests)) download request.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
softwareModuleId
required
integer <int64>
fileName
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

MD5 checksum download

Handles GET {@link DdiArtifact} MD5 checksum file download request.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
softwareModuleId
required
integer <int64>
fileName
required
string

Responses

Response samples

Content type
application/json
{
  • "exceptionClass": "string",
  • "errorCode": "string",
  • "message": "string",
  • "info": {
    }
}

Previously installed action

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
query Parameters
actionHistory
integer <int32>
Default: 0

Responses

Response samples

Content type
{}

Resource for software module (Deployment Base)

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
query Parameters
c
integer <int32>
Default: -1
actionHistory
string

(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.

Responses

Response samples

Content type
{}

Resource to request confirmation specific information for the controller

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string

Responses

Response samples

Content type
{}

Confirmation status of an action

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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>
query Parameters
c
integer <int32>
Default: -1
actionHistory
integer <int32>
Default: 0

Responses

Response samples

Content type
{}

Cancel an action

The Hawkbit 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.

Authorizations:
APIKEY
path Parameters
tenant
required
string
controllerId
required
string
actionId
required
integer <int64>

Responses

Response samples

Content type
{
  • "id": "11",
  • "cancelAction": {
    }
}