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 more detailed information about the action. The resource supports Etag based modification checks in order to save traffic. Note: deployments have to be confirmed in order to move on to the next action. Cancellations have to be confirmed or rejected.

Controller base poll resource

Curl

$ curl 'https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /TENANT_ID/controller/v1/CONTROLLER_ID HTTP/1.1
Host: ddi-api.host.com
Accept: application/hal+json

Request path parameter

Parameter Description

tenant

The tenant

controllerId

id of the controller

Response (Status 200) with an active deployment

Response fields

Path Type Description Allowed Values

config.polling

Object

suggested sleep time between polls

config.polling.sleep

String

sleep time in HH:MM:SS notation

_links

Object

Open Actions that the server has for the target

_links.deploymentBase

Object

Detailed deployment operation

_links.configData

Object

configuration data as key/value list

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 354

{
  "config" : {
    "polling" : {
      "sleep" : "12:00:00"
    }
  },
  "_links" : {
    "deploymentBase" : {
      "href" : "https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/3?c=-2129030598"
    },
    "configData" : {
      "href" : "https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/configData"
    }
  }
}

Response (Status 200) with an active cancellation

Response fields

Path Type Description Allowed Values

config.polling

Object

suggested sleep time between polls

config.polling.sleep

String

sleep time in HH:MM:SS notation

_links

Object

Open Actions that the server has for the target

_links.cancelAction

Object

Detailed deployment operation

_links.configData

Object

configuration data as key/value list

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 336

{
  "config" : {
    "polling" : {
      "sleep" : "12:00:00"
    }
  },
  "_links" : {
    "cancelAction" : {
      "href" : "https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/1"
    },
    "configData" : {
      "href" : "https://ddi-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 SP server might cancel an operation, e.g. an unfinished update has a sucessor. It is up to the provisiong target to decide to accept the cancelation or reject it.

Cancel an action

Curl

$ curl 'https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/6' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/6 HTTP/1.1
Host: ddi-api.host.com
Accept: application/hal+json

Request path parameter

Parameter Description

tenant

The tenant

controllerId

id of the controller

actionId

id of the action that needs to be canceled (typically identical to id field on the cancel action itself)

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

String

id of the action

cancelAction

Object

action that needs to be canceled

cancelAction.stopId

String

id of the action that needs to be canceled (typically identical to id field on the cancel action itself)

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 61

{
  "id" : "6",
  "cancelAction" : {
    "stopId" : "6"
  }
}

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://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/9/feedback' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "id" : "9",
  "time" : "20140511T121314",
  "status" : {
    "result" : {
      "finished" : "success"
    },
    "execution" : "closed",
    "details" : [ "Some feedback" ]
  }
}'

Request URL

POST /TENANT_ID/controller/v1/CONTROLLER_ID/cancelAction/9/feedback HTTP/1.1
Host: ddi-api.host.com
Content-Length: 183
Content-Type: application/json;charset=UTF-8

{
  "id" : "9",
  "time" : "20140511T121314",
  "status" : {
    "result" : {
      "finished" : "success"
    },
    "execution" : "closed",
    "details" : [ "Some feedback" ]
  }
}

Request path parameter

Parameter Description

tenant

The tenant

controllerId

id of the controller

actionId

id of the action that needs to be canceled (typically identical to id field on the cancel action itself)

Request fields

Path Type Description Allowed Values Mandatory

id

String

id of the action

time

String

time on the target device

status

Object

target action status

X

status.execution

enum

status of the action execution

['closed', 'proceeding', 'canceled','scheduled', 'rejected', 'resumed']

X

status.result

Object

result of the action execution

X

status.result.finished

enum

defined status of the result

['success', 'failure', 'none']

X

status.details

Array

List of details message information

Error responses

HTTP Status Code Reason Response Model

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 resgisters at the server it is requested to provide the meta information that will allow the server to identify the device on a hardware level (e.g. hardware revision, mac address, serial number etc.).

Response to a requested metadata pull from the provisioning target device.

Curl

$ curl 'https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/configData' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "mode" : "merge",
  "data" : {
    "VIN" : "JH4TB2H26CC000000",
    "hwRevision" : "2"
  },
  "id" : "",
  "time" : "20140511T121314",
  "status" : {
    "result" : {
      "finished" : "success"
    },
    "execution" : "closed",
    "details" : [ ]
  }
}'

Request URL

PUT /TENANT_ID/controller/v1/CONTROLLER_ID/configData HTTP/1.1
Host: ddi-api.host.com
Content-Length: 260
Content-Type: application/json;charset=UTF-8

{
  "mode" : "merge",
  "data" : {
    "VIN" : "JH4TB2H26CC000000",
    "hwRevision" : "2"
  },
  "id" : "",
  "time" : "20140511T121314",
  "status" : {
    "result" : {
      "finished" : "success"
    },
    "execution" : "closed",
    "details" : [ ]
  }
}

Request path parameter

Parameter Description

tenant

The tenant

controllerId

id of the controller

Request fields

Path Type Description Allowed Values Mandatory

id

String

id of the action

time

String

time on the target device

status

Object

target action status

X

status.execution

enum

status of the action execution

['closed', 'proceeding', 'canceled','scheduled', 'rejected', 'resumed']

X

status.result

Object

result of the action execution

X

status.result.finished

enum

defined status of the result

['success', 'failure', 'none']

X

status.details

Array

List of details message information

data

Object

configuration data as key/value list

X

mode

enum

Optional parameter to specify the update mode that should be applied when updating target attributes. Valid values are 'merge', 'replace', and 'remove'. Defaults to 'merge'.

['merge', 'replace', 'remove']

Error responses

HTTP Status Code Reason Response Model

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://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/4?actionHistory=10' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/4?actionHistory=10 HTTP/1.1
Host: ddi-api.host.com
Accept: application/hal+json

Request path parameter

Parameter Description

tenant

The tenant

controllerId

id of the controller

actionId

id of the action

Request query parameter

Parameter Description

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.

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-Length: 7173
Content-Type: application/hal+json;charset=UTF-8

{
  "id" : "4",
  "deployment" : {
    "download" : "forced",
    "update" : "forced",
    "maintenanceWindow" : "available",
    "chunks" : [ {
      "part" : "jvm",
      "version" : "1.0.46",
      "name" : "oneapp runtime",
      "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/11/filename/binary.tgz"
          },
          "download-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/11/filename/binary.tgz"
          },
          "md5sum-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/11/filename/binary.tgz.MD5SUM"
          },
          "md5sum" : {
            "href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/11/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/11/filename/file.signature"
          },
          "download-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/11/filename/file.signature"
          },
          "md5sum-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/11/filename/file.signature.MD5SUM"
          },
          "md5sum" : {
            "href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/11/filename/file.signature.MD5SUM"
          }
        }
      } ]
    }, {
      "part" : "os",
      "version" : "1.0.43",
      "name" : "one Firmware",
      "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/12/filename/binary.tgz"
          },
          "download-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/12/filename/binary.tgz"
          },
          "md5sum-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/12/filename/binary.tgz.MD5SUM"
          },
          "md5sum" : {
            "href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/12/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/12/filename/file.signature"
          },
          "download-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/12/filename/file.signature"
          },
          "md5sum-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/12/filename/file.signature.MD5SUM"
          },
          "md5sum" : {
            "href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/12/filename/file.signature.MD5SUM"
          }
        }
      } ],
      "metadata" : [ {
        "key" : "aMetadataKey",
        "value" : "Metadata value as defined in software module"
      } ]
    }, {
      "part" : "bApp",
      "version" : "1.0.63",
      "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/10/filename/binary.tgz"
          },
          "download-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/10/filename/binary.tgz"
          },
          "md5sum-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/10/filename/binary.tgz.MD5SUM"
          },
          "md5sum" : {
            "href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/10/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/10/filename/file.signature"
          },
          "download-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/10/filename/file.signature"
          },
          "md5sum-http" : {
            "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/10/filename/file.signature.MD5SUM"
          },
          "md5sum" : {
            "href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/10/filename/file.signature.MD5SUM"
          }
        }
      } ]
    } ]
  },
  "actionHistory" : {
    "status" : "RUNNING",
    "messages" : [ "Reboot", "Write firmware", "Download done", "Download failed. ErrorCode #5876745. Retry", "Started download" ]
  }
}

Response (Status 200) with a maintenance window defined but not active yet

In addition to the straight forward approach to inform the device to download and install the software in one transaction hawkBit supports the separation of download and installation into separate steps.

This feature is called Maintenance Window where the device is informed to download the software first and then when it enters a defined (maintenance) window the installation triggers follows as in the example above.

Response example

Note: artifact details not shown in this example.

HTTP/1.1 200 OK
Content-Length: 495
Content-Type: application/hal+json;charset=UTF-8

{
  "id" : "7",
  "deployment" : {
    "download" : "forced",
    "update" : "skip",
    "maintenanceWindow" : "unavailable",
    "chunks" : [ {
      "part" : "os",
      "version" : "1.0.81",
      "name" : "one Firmware",
      "artifacts" : [ ]
    }, {
      "part" : "bApp",
      "version" : "1.0.41",
      "name" : "oneapplication",
      "artifacts" : [ ]
    }, {
      "part" : "jvm",
      "version" : "1.0.74",
      "name" : "oneapp runtime",
      "artifacts" : [ ]
    } ]
  }
}

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://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/5/feedback' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -H 'Accept: application/hal+json' \
    -d '{
  "id" : "5",
  "time" : "20140511T121314",
  "status" : {
    "result" : {
      "progress" : {
        "of" : 5,
        "cnt" : 2
      },
      "finished" : "none"
    },
    "execution" : "closed",
    "details" : [ "Feddback message" ]
  }
}'

Request URL

POST /TENANT_ID/controller/v1/CONTROLLER_ID/deploymentBase/5/feedback HTTP/1.1
Host: ddi-api.host.com
Content-Length: 249
Content-Type: application/json;charset=UTF-8
Accept: application/hal+json

{
  "id" : "5",
  "time" : "20140511T121314",
  "status" : {
    "result" : {
      "progress" : {
        "of" : 5,
        "cnt" : 2
      },
      "finished" : "none"
    },
    "execution" : "closed",
    "details" : [ "Feddback message" ]
  }
}

Request path parameter

Parameter Description

tenant

The tenant

controllerId

id of the controller

actionId

id of the action

Request fields

Path Type Description Allowed Values Mandatory

id

String

id of the action

time

String

time on the target device

status

Object

target action status

X

status.execution

enum

status of the action execution

['closed', 'proceeding', 'canceled','scheduled', 'rejected', 'resumed']

X

status.result

Object

result of the action execution

X

status.result.finished

enum

defined status of the result

['success', 'failure', 'none']

X

status.result.progress

Object

progress assumption of the device

status.details

Array

List of details message information

Error responses

HTTP Status Code Reason Response Model

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}/softwaremodules/{softwareModuleId}/artifacts

Implementation notes

Returns all artifacts whichs is assigned to the software module

Returns artifacts of given software module

Curl

$ curl 'https://ddi-api.host.com/TENANT_ID/controller/v1/CONTROLLER_ID/softwaremodules/22/artifacts' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /TENANT_ID/controller/v1/CONTROLLER_ID/softwaremodules/22/artifacts HTTP/1.1
Host: ddi-api.host.com
Accept: application/hal+json

Request path parameter

Parameter Description

tenant

The tenant

controllerId

id of the controller

moduleId

id of the software module

Response (Status 200)

Response fields

Path Type Description Allowed Values

[]filename

String

list of artifacts

[]hashes

Object

list of artifacts

[]hashes.sha1

String

SHA1 hash of the artifact in Base 16 format

[]hashes.md5

String

MD5 hash of the artifact

[]hashes.sha256

String

SHA-256 hash of the artifact in Base 16 format

[]size

Number

size of the artifact

[]_links.download

Object

HTTPs Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download.

[]_links.md5sum

Object

HTTPs Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself.

[]_links.download-http

Object

HTTP Download resource for artifacts. The resource supports partial download as specified by RFC7233 (range requests). Keep in mind that the target needs to have the artifact assigned in order to be granted permission to download. (note: anonymous download needs to be enabled on the service account for non-TLS access)

[]_links.md5sum-http

Object

HTTP Download resource for MD5SUM file is an optional auto generated artifact that is especially useful for Linux based devices on order to check artifact consistency after download by using the md5sum command line tool. The MD5 and SHA1 are in addition available as metadata in the deployment command itself. (note: anonymous download needs to be enabled on the service account for non-TLS access)

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 921

[ {
  "filename" : "binaryFile",
  "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/binaryFile"
    },
    "download-http" : {
      "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/binaryFile"
    },
    "md5sum-http" : {
      "href" : "http://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/filename/binaryFile.MD5SUM"
    },
    "md5sum" : {
      "href" : "https://link-to-cdn.com/api/v1/TENANT_ID/download/controller/CONTROLLER_ID/softwaremodules/22/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