GET /rest/v1/targets

Implementation notes

Handles the GET request of retrieving all targets within SP. Required permission: READ_TARGET

Get paged list of targets

CURL

$ curl 'https://management-api.host.com/rest/v1/targets' -i -X GET

Request URL

A GET request is used to access the targets

GET /rest/v1/targets HTTP/1.1
Host: management-api.host.com

Request query parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

q

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

Request parameter example

GET /rest/v1/targets?limit=10&sort=name:ASC&offset=0&q=name%3D%3Da HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

size

Number

Current page size

total

Number

Total number of elements

content

Array

List of provisioning targets.

content[].createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

content[].address

String

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp.

content[].createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

content[].name

String

The name of the entity

content[].description

String

The description of the entity

content[].controllerId

String

The technical identifier of the entity

content[].updateStatus

enum

Current update status of the target.

['error', 'in_sync', 'pending', 'registered', 'unknown']

content[].securityToken

String

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings.

content[].requestAttributes

Boolean

Request re-transmission of target attributes.

content[].installedAt

Number

Installation time of current installed DistributionSet.

content[].lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

content[].lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

content[].ipAddress

String

Last known IP address of the target. Only presented if IP address of the target itself is known (connected directly through DDI API).

content[].lastControllerRequestAt

Number

Last time where the target polled the server, same as pollStatus.lastRequestAt.

Response example

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

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1610633137967,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633137985,
    "name" : "137",
    "description" : "My name is 137",
    "controllerId" : "137",
    "updateStatus" : "in_sync",
    "lastControllerRequestAt" : 1610633137966,
    "installedAt" : 1610633137982,
    "ipAddress" : "192.168.0.1",
    "address" : "http://192.168.0.1",
    "securityToken" : "a457155a01388a8ec09d789d7ff8c546",
    "requestAttributes" : true,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/137"
      }
    }
  } ],
  "total" : 1,
  "size" : 1
}

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 /rest/v1/targets

Implementation Notes

Handles the POST request of creating new targets within SP. The request body must always be a list of targets. Required Permission: CREATE_TARGET

Create list of targets

CURL

$ curl 'https://management-api.host.com/rest/v1/targets' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '[ {
  "securityToken" : "2345678DGGDGFTDzztgf",
  "address" : "https://192.168.0.1",
  "controllerId" : "123456",
  "name" : "controllerId",
  "description" : "test"
} ]'

Request URL

POST /rest/v1/targets HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 169
Host: management-api.host.com

[ {
  "securityToken" : "2345678DGGDGFTDzztgf",
  "address" : "https://192.168.0.1",
  "controllerId" : "123456",
  "name" : "controllerId",
  "description" : "test"
} ]

Request fields

Path Type Description Allowed Values Mandatory

[]controllerId

String

The technical identifier of the entity

X

[]name

String

The name of the entity

X

[]description

String

The description of the entity

[]address

String

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp.

[]securityToken

String

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings.

Response (Status 201)

Response fields

Path Type Description Allowed Values

[]controllerId

String

The technical identifier of the entity

[]name

String

The name of the entity

[]description

String

The description of the entity

[]address

String

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp.

[]createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

[]lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

[]lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

[]ipAddress

String

Last known IP address of the target. Only presented if IP address of the target itself is known (connected directly through DDI API).

[]createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

[]updateStatus

enum

Current update status of the target.

['error', 'in_sync', 'pending', 'registered', 'unknown']

[]securityToken

String

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings.

[]requestAttributes

Boolean

Request re-transmission of target attributes.

Response example

HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 497

[ {
  "createdBy" : "bumlux",
  "createdAt" : 1610633137709,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633137709,
  "name" : "controllerId",
  "description" : "test",
  "controllerId" : "123456",
  "updateStatus" : "unknown",
  "ipAddress" : "192.168.0.1",
  "address" : "https://192.168.0.1",
  "securityToken" : "2345678DGGDGFTDzztgf",
  "requestAttributes" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targets/123456"
    }
  }
} ]

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.

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.

DELETE /rest/v1/targets/{targetId}

Implementation Notes

Handles the DELETE request of deleting a single target within SP. Required Permission: DELETE_TARGET

Deleting a target

CURL

$ curl 'https://management-api.host.com/rest/v1/targets/137' -i -X DELETE

Request URL

DELETE /rest/v1/targets/137 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Response (Status 200)

Response example

HTTP/1.1 200 OK

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/targets/{targetId}

Implementation Notes

Handles the GET request of retrieving a single target within SP. Required Permission: READ_TARGET

Get single target

CURL

$ curl 'https://management-api.host.com/rest/v1/targets/137' -i -X GET

Request URL

GET /rest/v1/targets/137 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

address

String

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp.

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

name

String

The name of the entity

description

String

The description of the entity

controllerId

String

The technical identifier of the entity

updateStatus

enum

Current update status of the target.

['error', 'in_sync', 'pending', 'registered', 'unknown']

securityToken

String

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings.

requestAttributes

Boolean

Request re-transmission of target attributes.

installedAt

Number

Installation time of current installed DistributionSet.

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

ipAddress

String

Last known IP address of the target. Only presented if IP address of the target itself is known (connected directly through DDI API).

lastControllerRequestAt

Number

Last time where the target polled the server, same as pollStatus.lastRequestAt.

pollStatus

Object

Poll status of the target. In many scenarios that target will poll the update server on a regular basis to look for potential updates. If that poll does not happen it might imply that the target is offline.

pollStatus.lastRequestAt

Number

Last time when the target polled the server.

pollStatus.nextExpectedRequestAt

Number

Next expected time when the target polls the server.

pollStatus.overdue

Boolean

Defines if the target poll time is overdue based on the next expected poll time plus the configured overdue poll time threshold.

_links.assignedDS

Object

Links to assigned distribution sets.

_links.installedDS

Object

Links to installed distribution sets.

_links.attributes

Object

Links to attributes of the target.

_links.actions

Object

Links to actions of the target.

_links.metadata

Object

List of metadata.

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1610633139040,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633139063,
  "name" : "137",
  "description" : "My name is 137",
  "controllerId" : "137",
  "updateStatus" : "in_sync",
  "lastControllerRequestAt" : 1610633139040,
  "installedAt" : 1610633139061,
  "ipAddress" : "192.168.0.1",
  "address" : "http://192.168.0.1",
  "pollStatus" : {
    "lastRequestAt" : 1610633139040,
    "nextExpectedRequestAt" : 1610676339040,
    "overdue" : false
  },
  "securityToken" : "163c629ae766f61d4ddff611f53848a7",
  "requestAttributes" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137"
    },
    "assignedDS" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/assignedDS"
    },
    "installedDS" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/installedDS"
    },
    "attributes" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/attributes"
    },
    "actions" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions?offset=0&limit=50&sort=id:DESC"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/metadata?offset=0&limit=50{&sort,q}",
      "templated" : true
    }
  }
}

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

PUT /rest/v1/targets/{targetId}

Implementation Notes

Handles the PUT request of updating a target within SP. Required Permission: UPDATE_TARGET

Update a target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "securityToken" : "2345678DGGDGFTDzztgf",
  "requestAttributes" : true,
  "address" : "https://192.168.0.1",
  "controllerId" : "137",
  "name" : "newTargetName",
  "description" : "I've been updated"
}'

Request URL

PUT /rest/v1/targets/137 HTTP/1.1
Content-Length: 206
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com

{
  "securityToken" : "2345678DGGDGFTDzztgf",
  "requestAttributes" : true,
  "address" : "https://192.168.0.1",
  "controllerId" : "137",
  "name" : "newTargetName",
  "description" : "I've been updated"
}

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

name

String

The name of the entity

description

String

The description of the entity

controllerId

String

The technical identifier of the entity

address

String

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp.

securityToken

String

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings.

requestAttributes

Boolean

Request re-transmission of target attributes.

Response (Status 200)

Response fields

Path Type Description Allowed Values

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

address

String

The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp.

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

name

String

The name of the entity

description

String

The description of the entity

controllerId

String

The technical identifier of the entity

updateStatus

enum

Current update status of the target.

['error', 'in_sync', 'pending', 'registered', 'unknown']

securityToken

String

Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings.

requestAttributes

Boolean

Request re-transmission of target attributes.

installedAt

Number

Installation time of current installed DistributionSet.

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

ipAddress

String

Last known IP address of the target. Only presented if IP address of the target itself is known (connected directly through DDI API).

lastControllerRequestAt

Number

Last time where the target polled the server, same as pollStatus.lastRequestAt.

pollStatus

Object

Poll status of the target. In many scenarios that target will poll the update server on a regular basis to look for potential updates. If that poll does not happen it might imply that the target is offline.

pollStatus.lastRequestAt

Number

Last time when the target polled the server.

pollStatus.nextExpectedRequestAt

Number

Next expected time when the target polls the server.

pollStatus.overdue

Boolean

Defines if the target poll time is overdue based on the next expected poll time plus the configured overdue poll time threshold.

_links.assignedDS

Object

Links to assigned distribution sets.

_links.installedDS

Object

Links to installed distribution sets.

_links.attributes

Object

Links to attributes of the target.

_links.actions

Object

Links to actions of the target.

_links.metadata

Object

List of metadata.

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1610633138094,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633138123,
  "name" : "newTargetName",
  "description" : "I've been updated",
  "controllerId" : "137",
  "updateStatus" : "in_sync",
  "lastControllerRequestAt" : 1610633138093,
  "installedAt" : 1610633138110,
  "ipAddress" : "192.168.0.1",
  "address" : "https://192.168.0.1",
  "pollStatus" : {
    "lastRequestAt" : 1610633138093,
    "nextExpectedRequestAt" : 1610676338093,
    "overdue" : false
  },
  "securityToken" : "2345678DGGDGFTDzztgf",
  "requestAttributes" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137"
    },
    "assignedDS" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/assignedDS"
    },
    "installedDS" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/installedDS"
    },
    "attributes" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/attributes"
    },
    "actions" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions?offset=0&limit=50&sort=id:DESC"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/metadata?offset=0&limit=50{&sort,q}",
      "templated" : true
    }
  }
}

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 /rest/v1/targets/{targetId}/actions

Implementation Notes

Handles the GET request of retrieving the full action history of a specific target. Required Permission: READ_TARGET

List all actions of Target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/actions' -i -X GET

Request URL

GET /rest/v1/targets/137/actions HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Request query parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

q

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

Request parameter example

GET /rest/v1/targets/137/actions?limit=10&sort=id:ASC&offset=0&q=status%3D%3Dpending HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

size

Number

Current page size

total

Number

Total number of elements

content[]

Array

List of actions.

content[].createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

content[].createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

content[].lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

content[].lastModifiedAt

String

Entity was last modified at (timestamp UTC in milliseconds)

content[].type

String

Type of action.

['update', 'cancel']

content[].status

String

Status of action.

['finished', 'pending']

content[]._links

Object

The link to the action.

content[].id

Number

ID of the action.

content[].weight

Number

Weight of the action showing the importance of the update.

content[].maintenanceWindow

Object

Separation of download and install by defining a maintenance window for the installation.

content[].maintenanceWindow.schedule

String

Schedule for the maintenance window start in quartz cron notation, such as '0 15 10 * * ? 2018' for 10:15am every day during the year 2018.

content[].maintenanceWindow.duration

String

Duration of the window, such as '02:00:00' for 2 hours.

content[].maintenanceWindow.timezone

String

A time-zone offset from Greenwich/UTC, such as '+02:00'.

content[].maintenanceWindow.nextStartAt

Number

The time (timestamp UTC in milliseconds) of the next maintenance window start

Response example

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

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1610633138655,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633138663,
    "type" : "update",
    "status" : "finished",
    "weight" : 600,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/137/actions/71"
      }
    },
    "id" : 71,
    "forceType" : "forced"
  } ],
  "total" : 1,
  "size" : 1
}

Response example with Maintenance Window

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

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1610633139578,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633139591,
    "type" : "update",
    "status" : "finished",
    "weight" : 600,
    "maintenanceWindow" : {
      "schedule" : "39 7 15 14 1 ? 2021",
      "duration" : "00:01:00",
      "timezone" : "+01:00",
      "nextStartAt" : 1610633259000
    },
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/137/actions/75"
      }
    },
    "id" : 75,
    "forceType" : "forced"
  } ],
  "total" : 1,
  "size" : 1
}

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.

PUT /rest/v1/targets/{targetId}/actions/{actionId}

Implementation Notes

Handles the PUT request to switch an action from soft to forced. Required Permission: UPDATE_TARGET.

Update a target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/actions/65' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "forceType" : "forced"
}'

Request URL

PUT /rest/v1/targets/137/actions/65 HTTP/1.1
Content-Length: 28
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com

{
  "forceType" : "forced"
}

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

actionId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

forceType

String

Set to forced in order to switch action to forced mode.

X

Response (Status 200)

Response fields

Path Type Description Allowed Values

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

id

Number

ID of the action.

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

String

Entity was last modified at (timestamp UTC in milliseconds)

type

String

Type of action.

['update', 'cancel']

forceType

String

Force type of the action that provides a hint if the controller should apply the action immediately or whenever possible.

['forced', 'soft', 'timeforced']

status

String

Status of action.

['finished', 'pending']

_links.distributionset

Object

The link to the distribution set.

_links.status

Object

The link to all statuses of the action.

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1610633137856,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633137866,
  "type" : "update",
  "status" : "pending",
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions/65"
    },
    "distributionset" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/72"
    },
    "status" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions/65/status?offset=0&limit=50&sort=id:DESC"
    }
  },
  "id" : 65,
  "forceType" : "forced"
}

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.

DELETE /rest/v1/targets/{targetId}/actions/{actionId}

Implementation Notes

Cancels an active action, only active actions can be deleted. Required Permission: UPDATE_TARGET

Canceling an active action

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/actions/64' -i -X DELETE

Request URL

DELETE /rest/v1/targets/137/actions/64 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

actionId

The technical identifier of the entity

Request query parameter

Parameter Description

force

Force as boolean.

Request parameter example

DELETE /rest/v1/targets/137/actions/72?force=true HTTP/1.1
Host: management-api.host.com

Response (Status 204)

Response example

HTTP/1.1 204 No Content

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/targets/{targetId}/actions/{actionId}

Implementation Notes

Handles the GET request of retrieving a specific action on a specific target. Required Permission: READ_TARGET

Get assigned action of target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/actions/74' -i -X GET

Request URL

GET /rest/v1/targets/137/actions/74 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

actionId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

id

Number

ID of the action.

weight

Number

Weight of the action showing the importance of the update.

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

String

Entity was last modified at (timestamp UTC in milliseconds)

type

String

Type of action.

['update', 'cancel']

forceType

String

Force type of the action that provides a hint if the controller should apply the action immediately or whenever possible.

['forced', 'soft', 'timeforced']

forceTime

String

In case of timeforced mode the difference, measured in milliseconds, between the time the action should switch to forced and midnight, January 1, 1970 UTC.

status

String

Status of action.

['finished', 'pending']

maintenanceWindow

Object

Separation of download and install by defining a maintenance window for the installation.

maintenanceWindow.schedule

String

Schedule for the maintenance window start in quartz cron notation, such as '0 15 10 * * ? 2018' for 10:15am every day during the year 2018.

maintenanceWindow.duration

String

Duration of the window, such as '02:00:00' for 2 hours.

maintenanceWindow.timezone

String

A time-zone offset from Greenwich/UTC, such as '+02:00'.

maintenanceWindow.nextStartAt

Number

The time (timestamp UTC in milliseconds) of the next maintenance window start

_links.distributionset

Object

The link to the distribution set.

_links.status

Object

The link to all statuses of the action.

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1610633139353,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633139363,
  "type" : "update",
  "status" : "finished",
  "forceTime" : 0,
  "weight" : 600,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions/74"
    },
    "distributionset" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/81"
    },
    "status" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions/74/status?offset=0&limit=50&sort=id:DESC"
    }
  },
  "id" : 74,
  "forceType" : "timeforced"
}

Response example with Maintenance Window

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1610633136889,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633136959,
  "type" : "update",
  "status" : "finished",
  "forceTime" : 0,
  "weight" : 600,
  "maintenanceWindow" : {
    "schedule" : "36 7 15 14 1 ? 2021",
    "duration" : "00:01:00",
    "timezone" : "+01:00",
    "nextStartAt" : 1610633256000
  },
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions/58"
    },
    "distributionset" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/66"
    },
    "status" : {
      "href" : "https://management-api.host.com/rest/v1/targets/137/actions/58/status?offset=0&limit=50&sort=id:DESC"
    }
  },
  "id" : 58,
  "forceType" : "timeforced"
}

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/targets/{targetId}/actions/{actionId}/status

Implementation Notes

Handles the GET request of retrieving a specific action on a specific target. Required Permission: READ_TARGET

Get statuses of assigned action

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/actions/59/status' -i -X GET

Request URL

GET /rest/v1/targets/137/actions/59/status HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

actionId

The technical identifier of the entity

Request parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

Request parameter example

GET /rest/v1/targets/137/actions/68/status?limit=10&sort=id:ASC&offset=0 HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

size

Number

Current page size

total

Number

Total number of elements

content[]

Array

List of action status.

content[].id

Number

The technical identifier of the entity

content[].messages

String

Messages related to the status.

content[].reportedAt

String

Time at which the status was reported (server time).

content[].type

String

Type of the action status.

['finished', 'error', 'warning', 'pending', 'running', 'canceled', 'retrieved', 'canceling']

Response example

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

{
  "content" : [ {
    "type" : "finished",
    "messages" : [ null ],
    "reportedAt" : 1610633137114,
    "id" : 31
  }, {
    "type" : "running",
    "messages" : [ null ],
    "reportedAt" : 1610633137105,
    "id" : 30
  } ],
  "total" : 2,
  "size" : 2
}

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/targets/{targetId}/assignedDS

Implementation Notes

Handles the GET request of retrieving the assigned distribution set of an specific target. Required Permission: READ_TARGET

Get assigned distribution set of target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/assignedDS' -i -X GET

Request URL

GET /rest/v1/targets/137/assignedDS HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

name

String

The name of the entity

description

String

The description of the entity

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

type

String

The type of the distribution set.

requiredMigrationStep

Boolean

True if DS is a required migration step for another DS. As a result the DS’s assignment will not be cancelled when another DS is assigned (note: updatable only if DS is not yet assigned to a target)

complete

Boolean

True of the distribution set software module setup is complete as defined by the distribution set type.

deleted

Boolean

Deleted flag, used for soft deleted entities

version

String

Package version.

_links.type

Object

The type of the distribution set.

_links.metadata

Object

List of metadata.

_links.modules

Object

List of software modules.

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1610633138481,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633138483,
  "name" : "DS",
  "description" : "The descption of the distribution set.",
  "version" : "1.0",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1610633138465,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633138506,
    "name" : "application",
    "description" : "Description of the software module",
    "version" : "1.0.64",
    "type" : "application",
    "vendor" : "vendor Limited, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/236"
      }
    },
    "id" : 236
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1610633138469,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633138490,
    "name" : "app runtime",
    "description" : "Description of the software module",
    "version" : "1.0.29",
    "type" : "runtime",
    "vendor" : "vendor GmbH, Stuttgart, Germany",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/237"
      }
    },
    "id" : 237
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1610633138473,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633138498,
    "name" : "Firmware",
    "description" : "Description of the software module",
    "version" : "1.0.37",
    "type" : "os",
    "vendor" : "vendor Limited Inc, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/238"
      }
    },
    "id" : 238
  } ],
  "requiredMigrationStep" : false,
  "type" : "test_default_ds_type",
  "complete" : true,
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/77"
    },
    "modules" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/77/assignedSM?offset=0&limit=50{&sort}",
      "templated" : true
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsettypes/364"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/77/metadata?offset=0&limit=50{&sort,q}",
      "templated" : true
    }
  },
  "id" : 77
}

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

POST /rest/v1/targets/{targetId}/assignedDS (assign single distribution set)

Implementation Notes

Handles the POST request for assigning a distribution set to a specific target. Required Permission: READ_REPOSITORY and UPDATE_TARGET

Assign distribution set to target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/assignedDS' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "37 45 16 14 1 ? 2021",
    "timezone" : "+01:00"
  },
  "forcetime" : 1610633137219,
  "id" : 68,
  "type" : "timeforced"
}'

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Request query parameter

Parameter Description

offline

Offline update (set param to true) that is only reported but not managed by the service, e.g. defaults set in factory, manual updates or migrations from other update systems. A completed action is added to the history of the target(s). Target is set to IN_SYNC state as both assigend and installed DS are set. Note: only executed if the target has currently no running update.

Request fields

Path Type Description Allowed Values Mandatory

id

Number

The technical identifier of the entity

X

weight

Number

Importance of the assignment.

0 - 1000

when multi-assignment is enabled

forcetime

Number

Forcetime in milliseconds.

maintenanceWindow

Object

Separation of download and install by defining a maintenance window for the installation.

maintenanceWindow.schedule

String

Schedule for the maintenance window start in quartz cron notation, such as '0 15 10 * * ? 2018' for 10:15am every day during the year 2018.

maintenanceWindow.duration

String

Duration of the window, such as '02:00:00' for 2 hours.

maintenanceWindow.timezone

String

A time-zone offset from Greenwich/UTC, such as '+02:00'.

type

String

The type of the assignment.

['soft', 'forced','timeforced', 'downloadonly']

Request URL

POST /rest/v1/targets/137/assignedDS HTTP/1.1
Content-Length: 198
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com

{
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "37 45 16 14 1 ? 2021",
    "timezone" : "+01:00"
  },
  "forcetime" : 1610633137219,
  "id" : 68,
  "type" : "timeforced"
}

Response (Status 200)

Response fields

Path Type Description Allowed Values

assigned

Number

Targets that now have this distribution set assigned.

alreadyAssigned

Number

Targets that had this distribution set already assigned (in "offline" case this includes targets that have arbitrary updates running)

assignedActions

Array

The newly created actions as a result of this assignment

assignedActions.[].id

Number

ID of the action.

assignedActions.[]._links.self

Object

The link to the action.

total

Number

Overall assigned as part of this request.

Response example

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

{
  "alreadyAssigned" : 0,
  "assignedActions" : [ {
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/137/actions/61"
      }
    },
    "id" : 61
  } ],
  "assigned" : 1,
  "total" : 1
}

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 /rest/v1/targets/{targetId}/assignedDS (assign multiple distribution sets)

Implementation Notes

Handles the POST request for assigning multiple distribution sets to a specific target (only allowed id 'multi assignments' is enabled). Required Permission: READ_REPOSITORY and UPDATE_TARGET

Assign distribution sets to target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/assignedDS' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '[ {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "37 45 16 14 1 ? 2021",
    "timezone" : "+01:00"
  },
  "weight" : 500,
  "forcetime" : 1610633137457,
  "id" : 70,
  "type" : "timeforced"
}, {
  "weight" : 800,
  "id" : 69,
  "type" : "forced"
} ]'

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Request query parameter

Parameter Description

offline

Offline update (set param to true) that is only reported but not managed by the service, e.g. defaults set in factory, manual updates or migrations from other update systems. A completed action is added to the history of the target(s). Target is set to IN_SYNC state as both assigend and installed DS are set. Note: only executed if the target has currently no running update.

Request fields

Path Type Description Allowed Values Mandatory

[].id

Number

The technical identifier of the entity

X

[].weight

Number

Importance of the assignment.

0 - 1000

when multi-assignment is enabled

[].forcetime

Number

Forcetime in milliseconds.

[].maintenanceWindow

Object

Separation of download and install by defining a maintenance window for the installation.

[].maintenanceWindow.schedule

String

Schedule for the maintenance window start in quartz cron notation, such as '0 15 10 * * ? 2018' for 10:15am every day during the year 2018.

[].maintenanceWindow.duration

String

Duration of the window, such as '02:00:00' for 2 hours.

[].maintenanceWindow.timezone

String

A time-zone offset from Greenwich/UTC, such as '+02:00'.

[].type

String

The type of the assignment.

Request URL

POST /rest/v1/targets/137/assignedDS HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 276
Host: management-api.host.com

[ {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "37 45 16 14 1 ? 2021",
    "timezone" : "+01:00"
  },
  "weight" : 500,
  "forcetime" : 1610633137457,
  "id" : 70,
  "type" : "timeforced"
}, {
  "weight" : 800,
  "id" : 69,
  "type" : "forced"
} ]

Response (Status 200)

Response fields

Path Type Description Allowed Values

assigned

Number

Targets that now have this distribution set assigned.

alreadyAssigned

Number

Targets that had this distribution set already assigned (in "offline" case this includes targets that have arbitrary updates running)

assignedActions

Array

The newly created actions as a result of this assignment

assignedActions.[].id

Number

ID of the action.

assignedActions.[]._links.self

Object

The link to the action.

total

Number

Overall assigned as part of this request.

Response example

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

{
  "alreadyAssigned" : 0,
  "assignedActions" : [ {
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/137/actions/62"
      }
    },
    "id" : 62
  }, {
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/137/actions/63"
      }
    },
    "id" : 63
  } ],
  "assigned" : 2,
  "total" : 2
}

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters or 'multi assignments' is disabled

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 /rest/v1/targets/{targetId}/attributes

Implementation Notes

Handles the GET request of retrieving the attributes of a specific target. Reponse is a key/value list. Required Permission: READ_TARGET

Get attributes of target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/attributes' -i -X GET

Request URL

GET /rest/v1/targets/137/attributes HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Response (Status 200)

Response example

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

{
  "a" : "1",
  "b" : "2"
}

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/targets/{targetId}/installedDS

Implementation Notes

Handles the GET request of retrieving the installed distribution set of an specific target. Required Permission: READ_TARGET

Get installed distribution set of target

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/installedDS' -i -X GET

Request URL

GET /rest/v1/targets/137/installedDS HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

name

String

The name of the entity

description

String

The description of the entity

createdBy

String

Entity was originally created by User, AMQP-Controller, anonymous etc.)

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

lastModifiedBy

String

Entity was last modified by User, AMQP-Controller, anonymous etc.)

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

type

String

The type of the distribution set.

requiredMigrationStep

Boolean

True if DS is a required migration step for another DS. As a result the DS’s assignment will not be cancelled when another DS is assigned (note: updatable only if DS is not yet assigned to a target)

complete

Boolean

True of the distribution set software module setup is complete as defined by the distribution set type.

deleted

Boolean

Deleted flag, used for soft deleted entities

version

String

Package version.

_links.type

Object

The type of the distribution set.

_links.metadata

Object

List of metadata.

_links.modules

Object

List of software modules.

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1610633138345,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1610633138347,
  "name" : "DS",
  "description" : "The descption of the distribution set.",
  "version" : "1.0",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1610633138332,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633138355,
    "name" : "application",
    "description" : "Description of the software module",
    "version" : "1.0.68",
    "type" : "application",
    "vendor" : "vendor Limited, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/233"
      }
    },
    "id" : 233
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1610633138334,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633138362,
    "name" : "app runtime",
    "description" : "Description of the software module",
    "version" : "1.0.85",
    "type" : "runtime",
    "vendor" : "vendor GmbH, Stuttgart, Germany",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/234"
      }
    },
    "id" : 234
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1610633138337,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1610633138369,
    "name" : "Firmware",
    "description" : "Description of the software module",
    "version" : "1.0.79",
    "type" : "os",
    "vendor" : "vendor Limited Inc, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/235"
      }
    },
    "id" : 235
  } ],
  "requiredMigrationStep" : false,
  "type" : "test_default_ds_type",
  "complete" : true,
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/76"
    },
    "modules" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/76/assignedSM?offset=0&limit=50{&sort}",
      "templated" : true
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsettypes/360"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/76/metadata?offset=0&limit=50{&sort,q}",
      "templated" : true
    }
  },
  "id" : 76
}

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/targets/{targetId}/metadata

Implementation Notes

Get a paged list of meta data for a target. Required permission: READ_REPOSITORY

Get a paged list of meta data

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/metadata' -i -X GET

Request URL

GET /rest/v1/targets/137/metadata HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Request query parameter

Parameter Description

limit

The maximum number of entries in a page (default is 50).

sort

The query parameter sort allows to define the sort order for the result of a query. A sort criteria consists of the name of a field and the sort direction (ASC for ascending and DESC descending). The sequence of the sort criteria (multiple can be used) defines the sort order of the entities in the result.

offset

The paging offset (default is 0).

q

Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields.

Request parameter example

GET /rest/v1/targets/137/metadata?offset=1&limit=2&sort=key%3ADESC&q=key%3D%3Dknown* HTTP/1.1
Host: management-api.host.com

Response (Status 200)

Response fields

Path Type Description Allowed Values

total

Number

Total number of elements

size

Number

Current page size

content

Array

List of metadata.

content[].key

String

Metadata property key.

content[].value

String

Metadata property value.

Response example

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

{
  "content" : [ {
    "key" : "knownKey0",
    "value" : "knownValue0"
  }, {
    "key" : "knownKey1",
    "value" : "knownValue1"
  }, {
    "key" : "knownKey2",
    "value" : "knownValue2"
  }, {
    "key" : "knownKey3",
    "value" : "knownValue3"
  } ],
  "total" : 4,
  "size" : 4
}

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 /rest/v1/targets/{targetId}/metadata

Implementation Notes

Create a list of meta data entries Required permissions: READ_REPOSITORY and UPDATE_TARGET

Create a list of meta data entries

CURL

$ curl 'https://management-api.host.com/rest/v1/targets/137/metadata' -i -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '[ {
  "value" : "knownValue1",
  "key" : "knownKey1"
}, {
  "value" : "knownValue2",
  "key" : "knownKey2"
} ]'

Request URL

POST /rest/v1/targets/137/metadata HTTP/1.1
Content-Length: 110
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com

[ {
  "value" : "knownValue1",
  "key" : "knownKey1"
}, {
  "value" : "knownValue2",
  "key" : "knownKey2"
} ]

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

[]key

String

Metadata property key.

X

[]value

String

Metadata property value.

Response (Status 200)

Response example

HTTP/1.1 201 Created
Content-Length: 110
Content-Type: application/hal+json;charset=UTF-8

[ {
  "key" : "knownKey1",
  "value" : "knownValue1"
}, {
  "key" : "knownKey2",
  "value" : "knownValue2"
} ]

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.

DELETE /rest/v1/targets/{targetId}/metadata/{metadataKey}

Implementation Notes

Delete a single meta data. Required permission: UPDATE_REPOSITORY

Delete a single meta data

CURL

$ curl 'https://management-api.host.com/rest/v1/targets/137/metadata/knownKey' -i -X DELETE

Request URL

DELETE /rest/v1/targets/137/metadata/knownKey HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

key

The technical identifier of the entity

Response (Status 200)

Response example

HTTP/1.1 200 OK

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.

429 Too Many Request

Too many requests. The server will refuse further attempts and the client has to wait another second.

GET /rest/v1/targets/{targetId}/metadata/{metadataKey}

Implementation Notes

Get a single meta data value for a meta data key. Required permission: READ_REPOSITORY

Get a single meta data value

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/metadata/knownKey' -i -X GET

Request URL

GET /rest/v1/targets/137/metadata/knownKey HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

metadatakey

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

key

String

Metadata property key.

value

String

Metadata property value.

Response example

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

{
  "key" : "knownKey",
  "value" : "knownValue"
}

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.

PUT /rest/v1/targets/{targetId}/metadata/{metadataKey}

Implementation Notes

Update a single meta data value for speficic key. Required permission: UPDATE_REPOSITORY

Update a single meta data value

Curl

$ curl 'https://management-api.host.com/rest/v1/targets/137/metadata/knownKey' -i -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
  "value" : "valueForUpdate",
  "key" : "knownKey"
}'

Request URL

PUT /rest/v1/targets/137/metadata/knownKey HTTP/1.1
Content-Length: 54
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com

{
  "value" : "valueForUpdate",
  "key" : "knownKey"
}

Request path parameter

Parameter Description

targetId

The technical identifier of the entity

metadatakey

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

key

String

Metadata property key.

X

value

String

Metadata property value.

X

Response (Status 200)

Response fields

Path Type Description Allowed Values

key

String

Metadata property key.

value

String

Metadata property value.

Response example

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

{
  "key" : "knownKey",
  "value" : "valueForUpdate"
}

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.

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