GET /rest/v1/distributionsets

Implementation notes

Handles the GET request of retrieving all distribution sets within Bosch IoT Rollouts. Required permission: READ_REPOSITORY

Get paged list of Distribution Sets

Curl

$ curl 'https://management-api.host.com/rest/v1/distributionsets' -i -X GET \
    -H 'Accept: application/json'

Request URL

GET /rest/v1/distributionsets HTTP/1.1
Accept: application/json
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 query parameter example

GET /rest/v1/distributionsets?offset=1&limit=2&sort=version%3ADESC&q=name%3D%3DtestDS* HTTP/1.1
Accept: application/json
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 distribution sets.

content[].id

Number

The technical identifier of the entity

content[].name

String

The name of the entity

content[].description

String

The description of the entity

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

Number

Entity was last modified at (timestamp UTC in milliseconds)

content[].type

String

The type of the distribution set.

content[].typeName

String

The type name of the distribution set.

content[].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)

content[].complete

Boolean

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

content[].deleted

Boolean

Deleted flag, used for soft deleted entities

content[].version

String

Package version.

Response example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 2719

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406915552,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406915572,
    "name" : "DS",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0",
    "modules" : [ {
      "createdBy" : "bumlux",
      "createdAt" : 1682406915516,
      "lastModifiedBy" : "bumlux",
      "lastModifiedAt" : 1682406915626,
      "name" : "Firmware",
      "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
      "version" : "1.0.27",
      "type" : "os",
      "typeName" : "OS",
      "vendor" : "vendor Limited Inc, California",
      "deleted" : false,
      "encrypted" : false,
      "_links" : {
        "self" : {
          "href" : "https://management-api.host.com/rest/v1/softwaremodules/109"
        }
      },
      "id" : 109
    }, {
      "createdBy" : "bumlux",
      "createdAt" : 1682406915482,
      "lastModifiedBy" : "bumlux",
      "lastModifiedAt" : 1682406915608,
      "name" : "application",
      "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
      "version" : "1.0.83",
      "type" : "application",
      "typeName" : "Application",
      "vendor" : "vendor Limited, California",
      "deleted" : false,
      "encrypted" : false,
      "_links" : {
        "self" : {
          "href" : "https://management-api.host.com/rest/v1/softwaremodules/107"
        }
      },
      "id" : 107
    }, {
      "createdBy" : "bumlux",
      "createdAt" : 1682406915498,
      "lastModifiedBy" : "bumlux",
      "lastModifiedAt" : 1682406915589,
      "name" : "app runtime",
      "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
      "version" : "1.0.76",
      "type" : "runtime",
      "typeName" : "runtime",
      "vendor" : "vendor GmbH, Stuttgart, Germany",
      "deleted" : false,
      "encrypted" : false,
      "_links" : {
        "self" : {
          "href" : "https://management-api.host.com/rest/v1/softwaremodules/108"
        }
      },
      "id" : 108
    } ],
    "requiredMigrationStep" : false,
    "type" : "test_default_ds_type",
    "typeName" : "OS (FW) mandatory, runtime (FW) and app (SW) optional",
    "complete" : true,
    "deleted" : false,
    "valid" : true,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/distributionsets/34"
      }
    },
    "id" : 34
  } ],
  "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/distributionsets

Implementation Notes

Handles the POST request of creating new distribution sets within Bosch IoT Rollouts. The request body must always be a list of sets. Required permission: CREATE_REPOSITORY

Create Distribution Sets

CURL

$ curl 'https://management-api.host.com/rest/v1/distributionsets/' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '[ {
  "requiredMigrationStep" : false,
  "name" : "one",
  "description" : "dxsTt8omgq1E5h6TBKURS0ICPifrTzeEu2VkZosXTQkSTQ0hbL2dyu1Abt1NeaqrlT9RI3ceV0zyiR1kJCHO2NqriozMR87Nlqbs",
  "type" : "test_default_ds_type",
  "version" : "one",
  "modules" : [ {
    "id" : 105
  }, {
    "id" : 106
  } ]
}, {
  "requiredMigrationStep" : false,
  "name" : "two",
  "description" : "BVq29ar4Wb466hyrzAvxzpmpXV4WziBHu2K9cIZZyjFZoRVdEUnej2OUlBdBucvzTHflOyhJYefnVeoR4E6T5EwFhABOXZ7xH4iG",
  "type" : "test_default_ds_type",
  "version" : "two",
  "modules" : [ {
    "id" : 105
  }, {
    "id" : 106
  } ]
}, {
  "requiredMigrationStep" : true,
  "name" : "three",
  "description" : "yUsz2q3XAY3TjLqHay0RUxVTGAA9XAwc2Rh9nrwjcaWZxA8uDvm1xWVzZSGZd6UGNEnzcbvhkmVbnk3ghkBXnYacspJR3yfn2qpe",
  "type" : "test_default_ds_type",
  "version" : "three",
  "modules" : [ {
    "id" : 105
  }, {
    "id" : 106
  } ]
} ]'

Request URL

POST /rest/v1/distributionsets/ HTTP/1.1
Content-Type: application/json
Content-Length: 896
Host: management-api.host.com

[ {
  "requiredMigrationStep" : false,
  "name" : "one",
  "description" : "dxsTt8omgq1E5h6TBKURS0ICPifrTzeEu2VkZosXTQkSTQ0hbL2dyu1Abt1NeaqrlT9RI3ceV0zyiR1kJCHO2NqriozMR87Nlqbs",
  "type" : "test_default_ds_type",
  "version" : "one",
  "modules" : [ {
    "id" : 105
  }, {
    "id" : 106
  } ]
}, {
  "requiredMigrationStep" : false,
  "name" : "two",
  "description" : "BVq29ar4Wb466hyrzAvxzpmpXV4WziBHu2K9cIZZyjFZoRVdEUnej2OUlBdBucvzTHflOyhJYefnVeoR4E6T5EwFhABOXZ7xH4iG",
  "type" : "test_default_ds_type",
  "version" : "two",
  "modules" : [ {
    "id" : 105
  }, {
    "id" : 106
  } ]
}, {
  "requiredMigrationStep" : true,
  "name" : "three",
  "description" : "yUsz2q3XAY3TjLqHay0RUxVTGAA9XAwc2Rh9nrwjcaWZxA8uDvm1xWVzZSGZd6UGNEnzcbvhkmVbnk3ghkBXnYacspJR3yfn2qpe",
  "type" : "test_default_ds_type",
  "version" : "three",
  "modules" : [ {
    "id" : 105
  }, {
    "id" : 106
  } ]
} ]

Request fields

Path Type Description Allowed Values Mandatory

[]name

String

The name of the entity

X

[]description

String

The description of the entity

X

[]version

String

Package version.

X

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

[]type

String

The type of the distribution set.

X

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.

[]typeName

String

The type name 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

[]valid

Boolean

True by default and false after the distribution set is invalidated by the user.

[]version

String

Package version.

Response example

HTTP/1.1 201 Created
Content-Type: application/hal+json
Content-Length: 5504

[ {
  "createdBy" : "bumlux",
  "createdAt" : 1682406915226,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1682406915226,
  "name" : "one",
  "description" : "dxsTt8omgq1E5h6TBKURS0ICPifrTzeEu2VkZosXTQkSTQ0hbL2dyu1Abt1NeaqrlT9RI3ceV0zyiR1kJCHO2NqriozMR87Nlqbs",
  "version" : "one",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406915119,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406915119,
    "name" : "application",
    "description" : "tt3227c6AccCJHIej4WS9k9OMjhNAPDZn0tEO3K8xHZ8fKgdGTiQOR6NzjgIXVthsI1tQsRUm73X9CsbeCA7uAFv4rfOxib7eVpa",
    "version" : "1.0",
    "type" : "application",
    "typeName" : "Application",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/105"
      }
    },
    "id" : 105
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406915140,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406915140,
    "name" : "os",
    "description" : "cEOsji5tPOBsYZK9XdjAK4NC8eoCYowYdMQd0NBbn29ugPqRufI8vzmD9kyraLbtjcgObHLztUVDw1EwSmCHSSYsEr0RCLmdqpwr",
    "version" : "1.0",
    "type" : "os",
    "typeName" : "OS",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/106"
      }
    },
    "id" : 106
  } ],
  "requiredMigrationStep" : false,
  "type" : "test_default_ds_type",
  "typeName" : "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  "complete" : true,
  "deleted" : false,
  "valid" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/33"
    }
  },
  "id" : 33
}, {
  "createdBy" : "bumlux",
  "createdAt" : 1682406915233,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1682406915233,
  "name" : "two",
  "description" : "BVq29ar4Wb466hyrzAvxzpmpXV4WziBHu2K9cIZZyjFZoRVdEUnej2OUlBdBucvzTHflOyhJYefnVeoR4E6T5EwFhABOXZ7xH4iG",
  "version" : "two",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406915119,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406915119,
    "name" : "application",
    "description" : "tt3227c6AccCJHIej4WS9k9OMjhNAPDZn0tEO3K8xHZ8fKgdGTiQOR6NzjgIXVthsI1tQsRUm73X9CsbeCA7uAFv4rfOxib7eVpa",
    "version" : "1.0",
    "type" : "application",
    "typeName" : "Application",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/105"
      }
    },
    "id" : 105
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406915140,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406915140,
    "name" : "os",
    "description" : "cEOsji5tPOBsYZK9XdjAK4NC8eoCYowYdMQd0NBbn29ugPqRufI8vzmD9kyraLbtjcgObHLztUVDw1EwSmCHSSYsEr0RCLmdqpwr",
    "version" : "1.0",
    "type" : "os",
    "typeName" : "OS",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/106"
      }
    },
    "id" : 106
  } ],
  "requiredMigrationStep" : false,
  "type" : "test_default_ds_type",
  "typeName" : "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  "complete" : true,
  "deleted" : false,
  "valid" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/31"
    }
  },
  "id" : 31
}, {
  "createdBy" : "bumlux",
  "createdAt" : 1682406915240,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1682406915240,
  "name" : "three",
  "description" : "yUsz2q3XAY3TjLqHay0RUxVTGAA9XAwc2Rh9nrwjcaWZxA8uDvm1xWVzZSGZd6UGNEnzcbvhkmVbnk3ghkBXnYacspJR3yfn2qpe",
  "version" : "three",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406915119,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406915119,
    "name" : "application",
    "description" : "tt3227c6AccCJHIej4WS9k9OMjhNAPDZn0tEO3K8xHZ8fKgdGTiQOR6NzjgIXVthsI1tQsRUm73X9CsbeCA7uAFv4rfOxib7eVpa",
    "version" : "1.0",
    "type" : "application",
    "typeName" : "Application",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/105"
      }
    },
    "id" : 105
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406915140,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406915140,
    "name" : "os",
    "description" : "cEOsji5tPOBsYZK9XdjAK4NC8eoCYowYdMQd0NBbn29ugPqRufI8vzmD9kyraLbtjcgObHLztUVDw1EwSmCHSSYsEr0RCLmdqpwr",
    "version" : "1.0",
    "type" : "os",
    "typeName" : "OS",
    "vendor" : "Vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/106"
      }
    },
    "id" : 106
  } ],
  "requiredMigrationStep" : true,
  "type" : "test_default_ds_type",
  "typeName" : "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  "complete" : true,
  "deleted" : false,
  "valid" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/32"
    }
  },
  "id" : 32
} ]

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.

DELETE /rest/v1/distributionsets/{distributionSetId}

Implementation Notes

Handles the DELETE request for a single Distribution Set within Bosch IoT Rollouts. Required permission: DELETE_REPOSITORY

Delete Distribution Set

CURL

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

Request URL

DELETE /rest/v1/distributionsets/16 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

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/distributionsets/{distributionSetId}

Implementation Notes

Handles the GET request of retrieving a single distribution set within Bosch IoT Rollouts. Required permission: READ_REPOSITORY

Get Distribution Set

CURL

$ curl 'https://management-api.host.com/rest/v1/distributionsets/12' -i -X GET \
    -H 'Accept: application/json'

Request URL

GET /rest/v1/distributionsets/12 HTTP/1.1
Accept: application/json
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

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.

typeName

String

The type name 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

valid

Boolean

True by default and false after the distribution set is invalidated by the user.

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-Type: application/json
Content-Length: 2871

{
  "createdBy" : "bumlux",
  "createdAt" : 1682406897999,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1682406898057,
  "name" : "DS",
  "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
  "version" : "1.0",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406897941,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406898198,
    "name" : "Firmware",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.44",
    "type" : "os",
    "typeName" : "OS",
    "vendor" : "vendor Limited Inc, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/51"
      }
    },
    "id" : 51
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406897797,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406898137,
    "name" : "application",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.82",
    "type" : "application",
    "typeName" : "Application",
    "vendor" : "vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/49"
      }
    },
    "id" : 49
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406897873,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406898163,
    "name" : "app runtime",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.95",
    "type" : "runtime",
    "typeName" : "runtime",
    "vendor" : "vendor GmbH, Stuttgart, Germany",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/50"
      }
    },
    "id" : 50
  } ],
  "requiredMigrationStep" : false,
  "type" : "test_default_ds_type",
  "typeName" : "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  "complete" : true,
  "deleted" : false,
  "valid" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/12"
    },
    "modules" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/12/assignedSM?offset=0&limit=50"
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsettypes/124"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/12/metadata?offset=0&limit=50"
    }
  },
  "id" : 12
}

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/distributionsets/{distributionSetId}

Implementation Notes

Handles the UPDATE request for a single Distribution Set within Bosch IoT Rollouts. Required permission: UPDATE_REPOSITORY

Updating a Distribution Set

Curl

$ curl 'https://management-api.host.com/rest/v1/distributionsets/18' -i -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{
  "requiredMigrationStep" : true,
  "name" : "another Name",
  "description" : "a new description",
  "version" : "another Version"
}'

Request URL

PUT /rest/v1/distributionsets/18 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 135
Host: management-api.host.com

{
  "requiredMigrationStep" : true,
  "name" : "another Name",
  "description" : "a new description",
  "version" : "another Version"
}

Request path parameter

Parameter Description

distributionSetId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

name

String

The name of the entity

version

String

Package version.

description

String

The description of the entity

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)

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.

typeName

String

The type name 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

valid

Boolean

True by default and false after the distribution set is invalidated by the user.

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-Type: application/json
Content-Length: 2795

{
  "createdBy" : "bumlux",
  "createdAt" : 1682406904354,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1682406904738,
  "name" : "another Name",
  "description" : "a new description",
  "version" : "another Version",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406904201,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406904539,
    "name" : "Firmware",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.61",
    "type" : "os",
    "typeName" : "OS",
    "vendor" : "vendor Limited Inc, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/69"
      }
    },
    "id" : 69
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406904100,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406904464,
    "name" : "application",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.15",
    "type" : "application",
    "typeName" : "Application",
    "vendor" : "vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/67"
      }
    },
    "id" : 67
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406904158,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406904563,
    "name" : "app runtime",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.12",
    "type" : "runtime",
    "typeName" : "runtime",
    "vendor" : "vendor GmbH, Stuttgart, Germany",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/68"
      }
    },
    "id" : 68
  } ],
  "requiredMigrationStep" : true,
  "type" : "test_default_ds_type",
  "typeName" : "OS (FW) mandatory, runtime (FW) and app (SW) optional",
  "complete" : true,
  "deleted" : false,
  "valid" : true,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/18"
    },
    "modules" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/18/assignedSM?offset=0&limit=50"
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsettypes/140"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/18/metadata?offset=0&limit=50"
    }
  },
  "id" : 18
}

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/distributionsets/{distributionSetId}/assignedSM

Implementation Notes

Handles the GET request of retrieving a single distribution set within Bosch IoT Rollouts. Required permission: READ_REPOSITORY

Get assigned Software Modules

Curl

$ curl 'https://management-api.host.com/rest/v1/distributionsets/24/assignedSM' -i -X GET \
    -H 'Accept: application/json'

Request URL

GET /rest/v1/distributionsets/24/assignedSM HTTP/1.1
Accept: application/json
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

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/distributionsets/19/assignedSM?offset=1&limit=2&sort=version%3ADESC&q=name%3D%3Done* HTTP/1.1
Accept: application/json
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 software modules.

content[].id

Number

The technical identifier of the entity

content[].name

String

The name of the entity

content[].description

String

The description of the entity

content[].vendor

String

The software vendor.

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

Number

Entity was last modified at (timestamp UTC in milliseconds)

content[].type

String

The software module type of the entity

content[].version

String

Package version.

Response example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1904

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406910546,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406910765,
    "name" : "application",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.49",
    "type" : "application",
    "typeName" : "Application",
    "vendor" : "vendor Limited, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/85"
      }
    },
    "id" : 85
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406910568,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406910732,
    "name" : "app runtime",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.44",
    "type" : "runtime",
    "typeName" : "runtime",
    "vendor" : "vendor GmbH, Stuttgart, Germany",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/86"
      }
    },
    "id" : 86
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406910591,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406910794,
    "name" : "Firmware",
    "description" : "Updated Desc: 8eksTJWe7lkTUKLMEjSguV4r1GgTT2sDcxJ8QWJyrA2LJtDAeHRuGND5K9M7VZozHc9Xa0rHweMDjtSMfOBtzmWaD4OaViIAGBZx",
    "version" : "1.0.20",
    "type" : "os",
    "typeName" : "OS",
    "vendor" : "vendor Limited Inc, California",
    "deleted" : false,
    "encrypted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/87"
      }
    },
    "id" : 87
  } ],
  "total" : 3,
  "size" : 3
}

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/distributionsets/{distributionSetId}/assignedSM

Implementation Notes

Handles the POST request for assigning multiple software modules to a distribution set.The request body must always be a list of software module IDs. Required permissions: READ_REPOSITORY and UPDATE_REPOSITORY

Assign Software Modules to Distribution Set

CURL

$ curl 'https://management-api.host.com/rest/v1/distributionsets/26/assignedSM' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '[ {
  "id" : 91
}, {
  "id" : 92
} ]'

Request URL

POST /rest/v1/distributionsets/26/assignedSM HTTP/1.1
Content-Type: application/json
Content-Length: 36
Host: management-api.host.com

[ {
  "id" : 91
}, {
  "id" : 92
} ]

Request path parameter

Parameter Description

distributionSetId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

[]id

Number

The technical identifier of the entity

X

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.

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/distributionsets/{distributionSetId}/assignedSM/{softwareModuleId}

Implementation Notes

Delete a assignment. Required permission: UPDATE_REPOSITORY

Delete assignment of Software Module

CURL

$ curl 'https://management-api.host.com/rest/v1/distributionsets/11/assignedSM/48' -i -X DELETE \
    -H 'Content-Type: application/json'

Request URL

DELETE /rest/v1/distributionsets/11/assignedSM/48 HTTP/1.1
Content-Type: application/json
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

The technical identifier of the entity

softwareModuleId

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/distributionsets/{distributionSetId}/assignedTargets

Implementation Notes

Handles the GET request for retrieving assigned targets of a single distribution set. Required permissions: READ_REPOSITORY and READ_TARGET

Get assigned targets

Curl

$ curl 'https://management-api.host.com/rest/v1/distributionsets/10/assignedTargets' -i -X GET \
    -H 'Accept: application/json'

Request URL

GET /rest/v1/distributionsets/10/assignedTargets HTTP/1.1
Accept: application/json
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

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/distributionsets/17/assignedTargets?offset=1&limit=2&sort=name%3ADESC&q=controllerId%3D%3Dtarget* HTTP/1.1
Accept: application/json
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[Object]

List of provisioning targets.

Response example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 501

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406895129,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406895340,
    "name" : "targetExist",
    "controllerId" : "targetExist",
    "updateStatus" : "pending",
    "securityToken" : "a881ab6f5e2814f08fbc544369169bc7",
    "requestAttributes" : true,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/targetExist"
      }
    }
  } ],
  "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/distributionsets/{distributionSetId}/assignedTargets

Implementation Notes

Handles the POST request for assigning multiple targets to a distribution set.The request body must always be a list of target IDs. Required permissions: READ_REPOSITORY and UPDATE_TARGET

Assign targets to a distribution set

CURL

$ curl 'https://management-api.host.com/rest/v1/distributionsets/23/assignedTargets' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '[ {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target1",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target2",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target3",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target4",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target5",
  "type" : "timeforced"
} ]'

Request URL

POST /rest/v1/distributionsets/23/assignedTargets HTTP/1.1
Content-Type: application/json
Content-Length: 1027
Host: management-api.host.com

[ {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target1",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target2",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target3",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target4",
  "type" : "timeforced"
}, {
  "maintenanceWindow" : {
    "duration" : "00:10:00",
    "schedule" : "9 55 8 25 4 ? 2023",
    "timezone" : "+00:00"
  },
  "forcetime" : 1682406909177,
  "id" : "target5",
  "type" : "timeforced"
} ]

Request path parameter

Parameter Description

distributionSetId

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

String

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

[].confirmationRequired

Boolean

(Available with user consent flow active) Defines, if the confirmation is required for an action. Confirmation is required per default.

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
Content-Length: 710

{
  "alreadyAssigned" : 1,
  "assignedActions" : [ {
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/target2/actions/15"
      }
    },
    "id" : 15
  }, {
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/target3/actions/16"
      }
    },
    "id" : 16
  }, {
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/target4/actions/14"
      }
    },
    "id" : 14
  }, {
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/target5/actions/13"
      }
    },
    "id" : 13
  } ],
  "assigned" : 4,
  "total" : 5
}

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/distributionsets/{distributionSetId}/installedTargets

Implementation Notes

Handles the GET request for retrieving installed targets of a single distribution set. Required permissions: READ_REPOSITORY and READ_TARGET

Get installed targets

Curl

$ curl 'https://management-api.host.com/rest/v1/distributionsets/25/installedTargets' -i -X GET \
    -H 'Accept: application/json'

Request URL

GET /rest/v1/distributionsets/25/installedTargets HTTP/1.1
Accept: application/json
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

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/distributionsets/9/installedTargets?offset=1&limit=2&sort=name%3ADESC&q=controllerId%3D%3Dtarget* HTTP/1.1
Accept: application/json
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[Object]

List of provisioning targets.

Response example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 536

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406911929,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406912127,
    "name" : "targetExist",
    "controllerId" : "targetExist",
    "updateStatus" : "in_sync",
    "installedAt" : 1682406912102,
    "securityToken" : "5821a5d870ded9a9d57d12596a7d3e87",
    "requestAttributes" : true,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/targetExist"
      }
    }
  } ],
  "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.

GET /rest/v1/distributionsets/{distributionSetId}/autoAssignTargetFilters

Implementation Notes

Handles the GET request for retrieving assigned target filter queries of a single distribution set. Required permissions: READ_REPOSITORY and READ_TARGET

Get installed targets

Curl

$ curl 'https://management-api.host.com/rest/v1/distributionsets/22/autoAssignTargetFilters' -i -X GET \
    -H 'Accept: application/json'

Request URL

GET /rest/v1/distributionsets/22/autoAssignTargetFilters HTTP/1.1
Accept: application/json
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

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/distributionsets/7/autoAssignTargetFilters?offset=1&limit=2&sort=name%3ADESC&q=name%3D%3D*1 HTTP/1.1
Accept: application/json
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[Object]

List of target filter queries.

Response example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 977

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1682406908411,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406908411,
    "name" : "filter1",
    "query" : "name==a",
    "autoAssignDistributionSet" : 22,
    "autoAssignActionType" : null,
    "autoAssignWeight" : null,
    "confirmationRequired" : null,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targetfilters/2"
      }
    },
    "id" : 2
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1682406908480,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1682406908480,
    "name" : "filter2",
    "query" : "name==b",
    "autoAssignDistributionSet" : 22,
    "autoAssignActionType" : null,
    "autoAssignWeight" : null,
    "confirmationRequired" : null,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targetfilters/3"
      }
    },
    "id" : 3
  } ],
  "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

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/distributionsets/{distributionSetId}/metadata

Implementation Notes

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

Get a paged list of meta data

Curl

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

Request URL

GET /rest/v1/distributionsets/29/metadata HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

distributionSetId

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/distributionsets/28/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
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/distributionsets/{distributionSetId}/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/distributionsets/21/metadata' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '[ {
  "value" : "knownValue1",
  "key" : "knownKey1"
}, {
  "value" : "knownValue2",
  "key" : "knownKey2"
} ]'

Request URL

POST /rest/v1/distributionsets/21/metadata HTTP/1.1
Content-Type: application/json
Content-Length: 110
Host: management-api.host.com

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

Request path parameter

Parameter Description

distributionSetId

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-Type: application/hal+json
Content-Length: 110

[ {
  "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/distributionsets/{distributionSetId}/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/distributionsets/30/metadata/knownKey' -i -X DELETE

Request URL

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

Request path parameter

Parameter Description

distributionSetId

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/distributionsets/{distributionSetId}/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/distributionsets/27/metadata/knownKey' -i -X GET

Request URL

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

Request path parameter

Parameter Description

distributionSetId

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-Type: application/json
Content-Length: 50

{
  "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/distributionsets/{distributionSetId}/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/distributionsets/20/metadata/knownKey' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "value" : "valueForUpdate",
  "key" : "knownKey"
}'

Request URL

PUT /rest/v1/distributionsets/20/metadata/knownKey HTTP/1.1
Content-Type: application/json
Content-Length: 54
Host: management-api.host.com

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

Request path parameter

Parameter Description

distributionSetId

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-Type: application/hal+json
Content-Length: 54

{
  "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.

POST /rest/v1/distributionsets/{distributionSetId}/invalidate

Implementation Notes

Invalidate a distribution set. Once a distribution set is invalidated, it can not be valid again. An invalidated distribution set cannot be assigned to targets anymore. The distribution set that is going to be invalidated will be removed from all auto assignments. Furthermore, the user can choose to cancel all rollouts and (force) cancel all actions connected to this distribution set. Required permission: UPDATE_REPOSITORY, UPDATE_TARGET

Invalidate a distribution set

Curl

$ curl 'https://management-api.host.com/rest/v1/distributionsets/8/invalidate' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "cancelRollouts" : true,
  "actionCancelationType" : "soft"
}'

Request URL

POST /rest/v1/distributionsets/8/invalidate HTTP/1.1
Content-Type: application/json
Content-Length: 65
Host: management-api.host.com

{
  "cancelRollouts" : true,
  "actionCancelationType" : "soft"
}

Request path parameter

Parameter Description

distributionSetId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

actionCancelationType

String

Type of cancelation for actions referring to the given distribution set.

['force','soft','none']

X

cancelRollouts

Boolean

Defines if rollouts referring to this distribution set should be canceled.

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.

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

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