GET /rest/v1/rollouts

Implementation notes

Handles the GET request of retrieving all rollouts within SP. Required Permission: READ_ROLLOUT

Get paged list of Rollouts

Curl

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

Request URL

GET /rest/v1/rollouts HTTP/1.1
Accept: application/hal+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/rollouts?offset=0&limit=2&sort=id%3ADESC&q=name%3D%3DexampleRollout* HTTP/1.1
Accept: application/hal+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 rollouts

content[].id

Number

The technical identifier of the entity

content[].name

String

The name of the entity

content[].weight

Number

Weight of the resulting Actions

content[].deleted

Boolean

Deleted flag, used for soft deleted entities

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

String

target filter query language expression

content[].distributionSetId

Number

the ID of distributionset of this rollout

content[].status

String

the status of this rollout

['creating','ready','paused','running','finished']

content[].type

String

the type of this rollout

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

content[].totalTargets

Number

the total targets of a rollout

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 598

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1629287379576,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287379893,
    "name" : "exampleRollout",
    "description" : "exampleDescription",
    "targetFilterQuery" : "controllerId==exampleTarget*",
    "distributionSetId" : 15,
    "status" : "ready",
    "totalTargets" : 20,
    "deleted" : false,
    "type" : "forced",
    "weight" : 400,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/15"
      }
    },
    "id" : 15
  } ],
  "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/rollouts/{rolloutId}

Implementation Notes

Handles the GET request of retrieving a single rollout within SP. Required Permission: READ_ROLLOUT

Get Rollout

CURL

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

Request URL

GET /rest/v1/rollouts/2 HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

rolloutId

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

weight

Number

Weight of the resulting Actions

deleted

Boolean

Deleted flag, used for soft deleted entities

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)

targetFilterQuery

String

target filter query language expression

distributionSetId

Number

the ID of distributionset of this rollout

status

String

the status of this rollout

['creating','ready','paused','running','finished']

type

String

the type of this rollout

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

totalTargets

Number

the total targets of a rollout

totalTargetsPerStatus

Object

the total targets per status

_links.start

Object

Link to start the rollout in sync mode

_links.pause

Object

Link to pause a running rollout

_links.resume

Object

Link to resume a paused rollout

_links.groups

Object

Link to retrieve the groups a rollout

_links.approve

Object

Link to approve a rollout

_links.deny

Object

Link to deny a rollout

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1376

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287362759,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287363249,
  "name" : "exampleRollout",
  "description" : "exampleDescription",
  "targetFilterQuery" : "controllerId==exampleTarget*",
  "distributionSetId" : 2,
  "status" : "ready",
  "totalTargets" : 20,
  "totalTargetsPerStatus" : {
    "running" : 0,
    "notstarted" : 20,
    "scheduled" : 0,
    "cancelled" : 0,
    "finished" : 0,
    "error" : 0
  },
  "deleted" : false,
  "type" : "forced",
  "weight" : 400,
  "_links" : {
    "start" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/2/start"
    },
    "pause" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/2/pause"
    },
    "resume" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/2/resume"
    },
    "approve" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/2/approve{?remark}",
      "templated" : true
    },
    "deny" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/2/deny{?remark}",
      "templated" : true
    },
    "groups" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/2/deploygroups?offset=0&limit=50{&sort,q}",
      "templated" : true
    },
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/2"
    }
  },
  "id" : 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.

POST /rest/v1/rollouts

Implementation Notes

Handles the POST request of creating new rollout within SP. Required Permission: CREATE_ROLLOUT

Create Rollout with defined amount of groups

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts' -i -X POST \
    -H 'Content-Type: application/hal+json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "distributionSetId" : 6,
  "successCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "50"
  },
  "successAction" : {
    "expression" : "",
    "action" : "NEXTGROUP"
  },
  "targetFilterQuery" : "id==targets-*",
  "name" : "exampleRollout",
  "description" : "Rollout for all named targets",
  "amountGroups" : 10,
  "errorAction" : {
    "expression" : "",
    "action" : "PAUSE"
  },
  "type" : "forced",
  "errorCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "80"
  }
}'

Request URL

POST /rest/v1/rollouts HTTP/1.1
Content-Type: application/hal+json
Accept: application/hal+json
Content-Length: 510
Host: management-api.host.com

{
  "distributionSetId" : 6,
  "successCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "50"
  },
  "successAction" : {
    "expression" : "",
    "action" : "NEXTGROUP"
  },
  "targetFilterQuery" : "id==targets-*",
  "name" : "exampleRollout",
  "description" : "Rollout for all named targets",
  "amountGroups" : 10,
  "errorAction" : {
    "expression" : "",
    "action" : "PAUSE"
  },
  "type" : "forced",
  "errorCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "80"
  }
}

Request fields

Path Type Description Allowed Values Mandatory

name

String

The name of the entity

X

weight

Number

Weight of the resulting Actions

0 - 1000

when multi-assignment is enabled

name

String

The name of the entity

X

type

String

the type of this rollout

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

distributionSetId

Number

the ID of distributionset of this rollout

X

targetFilterQuery

String

target filter query language expression

X

amountGroups

Number

the amount of groups the rollout should split targets into

X

description

String

The description of the entity

successCondition

Object

the success condition which takes in place to evaluate if a rollout group is successful and so the next group can be started

successCondition.condition

String

the type of the condition

['threshold']

successCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

successAction

Object

the success action which takes in place to execute in case the success action is fulfilled

successAction.action

String

the success action to execute

['nextgroup']

successAction.expression

String

the expression for the success action

errorCondition

Object

the error condition which takes in place to evaluate if a rollout group encounter errors

errorCondition.condition

String

the type of the condition

['threshold']

errorCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

errorAction

Object

the error action which is executed if the error condition is fulfilled

errorAction.action

String

the error action to execute

['pause']

errorAction.expression

String

the expression for the error action

Response (Status 201)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

name

String

The name of the entity

weight

Number

Weight of the resulting Actions

deleted

Boolean

Deleted flag, used for soft deleted entities

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)

targetFilterQuery

String

target filter query language expression

distributionSetId

Number

the ID of distributionset of this rollout

status

String

the status of this rollout

['creating','ready','paused','running','finished']

type

String

the type of this rollout

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

totalTargets

Number

the total targets of a rollout

totalTargetsPerStatus

Object

the total targets per status

_links.start

Object

Link to start the rollout in sync mode

_links.pause

Object

Link to pause a running rollout

_links.resume

Object

Link to resume a paused rollout

_links.groups

Object

Link to retrieve the groups a rollout

_links.approve

Object

Link to approve a rollout

_links.deny

Object

Link to deny a rollout

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287368338,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287368338,
  "name" : "exampleRollout",
  "description" : "Rollout for all named targets",
  "targetFilterQuery" : "id==targets-*",
  "distributionSetId" : 6,
  "status" : "creating",
  "totalTargets" : 20,
  "totalTargetsPerStatus" : {
    "running" : 0,
    "notstarted" : 20,
    "scheduled" : 0,
    "cancelled" : 0,
    "finished" : 0,
    "error" : 0
  },
  "deleted" : false,
  "type" : "forced",
  "_links" : {
    "start" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/6/start"
    },
    "pause" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/6/pause"
    },
    "resume" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/6/resume"
    },
    "approve" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/6/approve{?remark}",
      "templated" : true
    },
    "deny" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/6/deny{?remark}",
      "templated" : true
    },
    "groups" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/6/deploygroups?offset=0&limit=50{&sort,q}",
      "templated" : true
    },
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/6"
    }
  },
  "id" : 6
}

Create Rollout with groups definition

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/hal+json' \
    -d '{
  "distributionSetId" : 8,
  "successCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "50"
  },
  "successAction" : {
    "expression" : "",
    "action" : "NEXTGROUP"
  },
  "targetFilterQuery" : "id==targets-*",
  "name" : "exampleRolloutWithDefinedGroups",
  "description" : "Rollout for all named targets",
  "groups" : [ {
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "90"
    },
    "targetPercentage" : 20,
    "successAction" : {
      "expression" : "",
      "action" : "NEXTGROUP"
    },
    "targetFilterQuery" : "name==targets-1*",
    "name" : "Group1",
    "description" : "Group1desc",
    "errorAction" : {
      "expression" : "",
      "action" : "PAUSE"
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "30"
    }
  }, {
    "successCondition" : {
      "condition" : "THRESHOLD"
    },
    "targetPercentage" : 100,
    "successAction" : {
      "action" : "NEXTGROUP"
    },
    "name" : "Group2",
    "description" : "Group2desc"
  } ],
  "errorAction" : {
    "expression" : "",
    "action" : "PAUSE"
  },
  "errorCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "80"
  }
}'

Request URL

POST /rest/v1/rollouts HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Content-Length: 1205
Host: management-api.host.com

{
  "distributionSetId" : 8,
  "successCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "50"
  },
  "successAction" : {
    "expression" : "",
    "action" : "NEXTGROUP"
  },
  "targetFilterQuery" : "id==targets-*",
  "name" : "exampleRolloutWithDefinedGroups",
  "description" : "Rollout for all named targets",
  "groups" : [ {
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "90"
    },
    "targetPercentage" : 20,
    "successAction" : {
      "expression" : "",
      "action" : "NEXTGROUP"
    },
    "targetFilterQuery" : "name==targets-1*",
    "name" : "Group1",
    "description" : "Group1desc",
    "errorAction" : {
      "expression" : "",
      "action" : "PAUSE"
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "30"
    }
  }, {
    "successCondition" : {
      "condition" : "THRESHOLD"
    },
    "targetPercentage" : 100,
    "successAction" : {
      "action" : "NEXTGROUP"
    },
    "name" : "Group2",
    "description" : "Group2desc"
  } ],
  "errorAction" : {
    "expression" : "",
    "action" : "PAUSE"
  },
  "errorCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "80"
  }
}

Request fields

Path Type Description Allowed Values Mandatory

name

String

The name of the entity

X

weight

Number

Weight of the resulting Actions

0 - 1000

when multi-assignment is enabled

distributionSetId

Number

the ID of distributionset of this rollout

X

targetFilterQuery

String

target filter query language expression

X

description

String

The description of the entity

successCondition

Object

the success condition which takes in place to evaluate if a rollout group is successful and so the next group can be started

successCondition.condition

String

the type of the condition

['threshold']

successCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

successAction

Object

the success action which takes in place to execute in case the success action is fulfilled

successAction.action

String

the success action to execute

['nextgroup']

successAction.expression

String

the expression for the success action

errorCondition

Object

the error condition which takes in place to evaluate if a rollout group encounter errors

errorCondition.condition

String

the type of the condition

['threshold']

errorCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

errorAction

Object

the error action which is executed if the error condition is fulfilled

errorAction.action

String

the error action to execute

['pause']

errorAction.expression

String

the expression for the error action

groups

Array

the list of group definitions

X

groups[].name

String

The name of the entity

X

groups[].description

String

The description of the entity

X

groups[].targetFilterQuery

String

target filter query language expression that selects a subset of targets which match the target filter of the Rollout

groups[].targetPercentage

Number

percentage of remaining and matching targets that should be added to this group

0..100

groups[].successCondition

Object

the success condition which takes in place to evaluate if a rollout group is successful and so the next group can be started

groups[].successCondition.condition

String

the type of the condition

['threshold']

groups[].successCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

groups[].successAction

Object

the success action which takes in place to execute in case the success action is fulfilled

groups[].successAction.action

String

the success action to execute

['nextgroup']

groups[].successAction.expression

String

the expression for the success action

groups[].errorCondition

Object

the error condition which takes in place to evaluate if a rollout group encounter errors

groups[].errorCondition.condition

String

the type of the condition

['threshold']

groups[].errorCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

groups[].errorAction

Object

the error action which is executed if the error condition is fulfilled

groups[].errorAction.action

String

the error action to execute

['pause']

groups[].errorAction.expression

String

the expression for the error action

Response (Status 201)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

name

String

The name of the entity

weight

Number

Weight of the resulting Actions

deleted

Boolean

Deleted flag, used for soft deleted entities

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)

targetFilterQuery

String

target filter query language expression

distributionSetId

Number

the ID of distributionset of this rollout

status

String

the status of this rollout

['creating','ready','paused','running','finished']

type

String

the type of this rollout

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

totalTargets

Number

the total targets of a rollout

totalTargetsPerStatus

Object

the total targets per status

_links.start

Object

Link to start the rollout in sync mode

_links.pause

Object

Link to pause a running rollout

_links.resume

Object

Link to resume a paused rollout

_links.groups

Object

Link to retrieve the groups a rollout

_links.approve

Object

Link to approve a rollout

_links.deny

Object

Link to deny a rollout

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287370333,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287370333,
  "name" : "exampleRolloutWithDefinedGroups",
  "description" : "Rollout for all named targets",
  "targetFilterQuery" : "id==targets-*",
  "distributionSetId" : 8,
  "status" : "creating",
  "totalTargets" : 10,
  "totalTargetsPerStatus" : {
    "running" : 0,
    "notstarted" : 10,
    "scheduled" : 0,
    "cancelled" : 0,
    "finished" : 0,
    "error" : 0
  },
  "deleted" : false,
  "type" : "forced",
  "_links" : {
    "start" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/8/start"
    },
    "pause" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/8/pause"
    },
    "resume" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/8/resume"
    },
    "approve" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/8/approve{?remark}",
      "templated" : true
    },
    "deny" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/8/deny{?remark}",
      "templated" : true
    },
    "groups" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/8/deploygroups?offset=0&limit=50{&sort,q}",
      "templated" : true
    },
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/8"
    }
  },
  "id" : 8
}

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.

POST /rest/v1/rollouts/{rolloutId}/start

Implementation Notes

Handles the POST request of starting a created rollout within SP. Required Permission: HANDLE_ROLLOUT

Start Rollout

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts/12/start' -i -X POST \
    -H 'Accept: application/hal+json'

Request URL

POST /rest/v1/rollouts/12/start HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

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/rollouts/{rolloutId}/pause

Implementation Notes

Handles the POST request of pausing a running rollout within SP. Required Permission: HANDLE_ROLLOUT

Pause Rollout

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts/5/pause' -i -X POST \
    -H 'Accept: application/hal+json'

Request URL

POST /rest/v1/rollouts/5/pause HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

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

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/rollouts/{rolloutId}/resume

Implementation Notes

Handles the POST request of resuming a paused rollout within SP. Required Permission: HANDLE_ROLLOUT

Resume Rollout

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts/4/resume' -i -X POST \
    -H 'Accept: application/hal+json'

Request URL

POST /rest/v1/rollouts/4/resume HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

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

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.

DELETE /rest/v1/rollouts/{rolloutId}

Implementation Notes

Handles the DELETE request of deleting a rollout within SP. Required Permission: DELETE_ROLLOUT

Deleting a rollout

CURL

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

Request URL

DELETE /rest/v1/rollouts/11 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

rolloutId

The name of the entity

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/rollouts/{rolloutId}/deploygroups

Implementation Notes

Handles the GET request of retrieving all deploy groups of a specific rollout within SP. Required Permission: READ_ROLLOUT

Get Deploy Groups

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts/13/deploygroups' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /rest/v1/rollouts/13/deploygroups HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

rolloutId

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 query parameter example

GET /rest/v1/rollouts?offset=0&limit=2&sort=id%3ADESC&q=name%3D%3DexampleRollout* HTTP/1.1
Accept: application/hal+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 rollouts

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

String

the status of this rollout group

['creating','ready','paused','running','finished']

content[].totalTargets

Number

the total targets of a rollout

content[].targetFilterQuery

String

target filter query language expression that selects a subset of targets which match the target filter of the Rollout

content[].targetPercentage

Number

percentage of remaining and matching targets that should be added to this group

content[].successCondition

Object

the success condition which takes in place to evaluate if a rollout group is successful and so the next group can be started

content[].successCondition.condition

String

the type of the condition

content[].successCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

content[].successAction

Object

the success action which takes in place to execute in case the success action is fulfilled

content[].successAction.action

String

the success action to execute

content[].successAction.expression

String

the expression for the success action

content[].errorCondition

Object

the error condition which takes in place to evaluate if a rollout group encounter errors

content[].errorCondition.condition

String

the type of the condition

content[].errorCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

content[].errorAction

Object

the error action which is executed if the error condition is fulfilled

content[].errorAction.action

String

the error action to execute

content[].errorAction.expression

String

the expression for the error action

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 8096

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377310,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377746,
    "name" : "group-1",
    "description" : "group-1",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 10.0,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/113"
      }
    },
    "id" : 113
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377311,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377757,
    "name" : "group-2",
    "description" : "group-2",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 11.1111,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/114"
      }
    },
    "id" : 114
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377312,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377757,
    "name" : "group-3",
    "description" : "group-3",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 12.5,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/115"
      }
    },
    "id" : 115
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377312,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377758,
    "name" : "group-4",
    "description" : "group-4",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 14.2857,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/116"
      }
    },
    "id" : 116
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377313,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377758,
    "name" : "group-5",
    "description" : "group-5",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 16.6667,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/117"
      }
    },
    "id" : 117
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377314,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377758,
    "name" : "group-6",
    "description" : "group-6",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 20.0,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/118"
      }
    },
    "id" : 118
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377314,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377758,
    "name" : "group-7",
    "description" : "group-7",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 25.0,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/119"
      }
    },
    "id" : 119
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377315,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377758,
    "name" : "group-8",
    "description" : "group-8",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 33.3333,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/120"
      }
    },
    "id" : 120
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377316,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377758,
    "name" : "group-9",
    "description" : "group-9",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 50.0,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/121"
      }
    },
    "id" : 121
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287377317,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287377759,
    "name" : "group-10",
    "description" : "group-10",
    "successCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "10"
    },
    "successAction" : {
      "action" : "NEXTGROUP",
      "expression" : ""
    },
    "errorCondition" : {
      "condition" : "THRESHOLD",
      "expression" : "50"
    },
    "errorAction" : {
      "action" : "PAUSE",
      "expression" : ""
    },
    "targetFilterQuery" : "",
    "targetPercentage" : 100.0,
    "status" : "ready",
    "totalTargets" : 2,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/rollouts/13/deploygroups/122"
      }
    },
    "id" : 122
  } ],
  "total" : 10,
  "size" : 10
}

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/rollouts/{rolloutId}/deploygroups/{deployGroupId}

Implementation Notes

Handles the GET request of a single deploy group of a specific rollout within SP. Required Permission: READ_ROLLOUT

Get Deploy Groups

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts/16/deploygroups/143' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /rest/v1/rollouts/16/deploygroups/143 HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

rolloutId

The technical identifier of the entity

deployGroupId

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)

status

String

the status of this rollout group

['creating','ready','paused','running','finished']

totalTargets

Number

the total targets of a rollout

totalTargetsPerStatus

Object

the total targets per status

targetFilterQuery

String

target filter query language expression that selects a subset of targets which match the target filter of the Rollout

targetPercentage

Number

percentage of remaining and matching targets that should be added to this group

successCondition

Object

the success condition which takes in place to evaluate if a rollout group is successful and so the next group can be started

successCondition.condition

String

the type of the condition

successCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

successAction

Object

the success action which takes in place to execute in case the success action is fulfilled

successAction.action

String

the success action to execute

successAction.expression

String

the expression for the success action

errorCondition

Object

the error condition which takes in place to evaluate if a rollout group encounter errors

errorCondition.condition

String

the type of the condition

errorCondition.expression

String

the expression according to the condition, e.g. the value of threshold in percentage

errorAction

Object

the error action which is executed if the error condition is fulfilled

errorAction.action

String

the error action to execute

errorAction.expression

String

the expression for the error action

Response example

HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 889

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287380560,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287381095,
  "name" : "group-1",
  "description" : "group-1",
  "successCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "10"
  },
  "successAction" : {
    "action" : "NEXTGROUP",
    "expression" : ""
  },
  "errorCondition" : {
    "condition" : "THRESHOLD",
    "expression" : "50"
  },
  "errorAction" : {
    "action" : "PAUSE",
    "expression" : ""
  },
  "targetFilterQuery" : "",
  "targetPercentage" : 10.0,
  "status" : "ready",
  "totalTargets" : 2,
  "totalTargetsPerStatus" : {
    "running" : 0,
    "notstarted" : 2,
    "scheduled" : 0,
    "cancelled" : 0,
    "finished" : 0,
    "error" : 0
  },
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/rollouts/16/deploygroups/143"
    }
  },
  "id" : 143
}

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/rollouts/{rolloutId}/deploygroups/{deployGroupId}/targets

Implementation Notes

Handles the GET request of retrieving all targets of a single deploy group of a specific rollout within SP. Required Permissions: READ_ROLLOUT, READ_TARGET.

Get Deploy Group Targets

CURL

$ curl 'https://management-api.host.com/rest/v1/rollouts/14/deploygroups/123/targets' -i -X GET \
    -H 'Accept: application/hal+json'

Request URL

GET /rest/v1/rollouts/14/deploygroups/123/targets HTTP/1.1
Accept: application/hal+json
Host: management-api.host.com

Request path parameter

Parameter Description

rolloutId

The technical identifier of the entity

deployGroupId

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 query parameter example

GET /rest/v1/rollouts/3/deploygroups/21/targets?offset=0&limit=2&sort=name%3AASC&q=controllerId%3D%3DexampleTarget0 HTTP/1.1
Accept: application/hal+json
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

class java.lang.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

class java.lang.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[].installedAt

class java.lang.Long

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

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1629287378158,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287378158,
    "name" : "exampleTarget-00006",
    "description" : "exampleTarget6",
    "controllerId" : "exampleTarget-00006",
    "updateStatus" : "unknown",
    "securityToken" : "917ae4d436c955d0e9fedd00d8a0ed94",
    "requestAttributes" : true,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/exampleTarget-00006"
      }
    }
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287378165,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287378165,
    "name" : "exampleTarget-00018",
    "description" : "exampleTarget18",
    "controllerId" : "exampleTarget-00018",
    "updateStatus" : "unknown",
    "securityToken" : "a4fa5ab832acce9dc0108bf63b321541",
    "requestAttributes" : true,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targets/exampleTarget-00018"
      }
    }
  } ],
  "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.

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