GET /rest/v1/targetfilters

Implementation notes

Handles the GET request of retrieving all target filter queries within SP. Required permission: READ_TARGET

Get paged list of target filter queries

CURL

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

Request URL

A GET request is used to access the target filter queries

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

Request query parameter

Parameter Description

limit

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

sort

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

offset

The paging offset (default is 0).

q

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

Request parameter example

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

Response (Status 200)

Response fields

Path Type Description Allowed Values

size

Number

Current page size

total

Number

Total number of elements

content

Array

List of target filter queries.

content[].id

Number

The technical identifier of the entity

content[].name

String

The name of the entity

content[].query

String

target filter query expression

content[].autoAssignDistributionSet

Number

Auto assign distribution set id

content[].autoAssignActionType

String

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

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

content[].createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

content[].createdBy

String

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

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

Response example

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

{
  "content" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1629287363479,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287363493,
    "name" : "filter1",
    "query" : "name==*",
    "autoAssignDistributionSet" : 2,
    "autoAssignActionType" : "forced",
    "autoAssignWeight" : null,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/targetfilters/2"
      }
    },
    "id" : 2
  } ],
  "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/targetfilters

Implementation Notes

Handles the POST request to create a new target filter query within SP. Required permission: CREATE_TARGET

Create a target filter query

CURL

$ curl 'https://management-api.host.com/rest/v1/targetfilters' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "query" : "name==*",
  "name" : "filter1"
}'

Request URL

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

{
  "query" : "name==*",
  "name" : "filter1"
}

Request fields

Path Type Description Allowed Values Mandatory

name

String

The name of the entity

X

query

String

target filter query expression

X

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

query

String

target filter query expression

autoAssignDistributionSet

Number

Auto assign distribution set id

autoAssignActionType

String

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

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

autoAssignWeight

Number

Weight of the resulting Actions

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

createdBy

String

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

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

lastModifiedBy

String

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

_links.autoAssignDS

Object

Link to manage the auto assign distribution set

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287363723,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287363723,
  "name" : "filter1",
  "query" : "name==*",
  "autoAssignDistributionSet" : null,
  "autoAssignActionType" : null,
  "autoAssignWeight" : null,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/3"
    },
    "autoAssignDS" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/3/autoAssignDS"
    }
  },
  "id" : 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, data volume restriction applies or quota limit exceeded.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

409 Conflict

E.g. in case an entity is created or modified by another user in another request at the same time. You may retry your modification request.

See Error body

415 Unsupported Media Type

The request was attempt with a media-type which is not supported by the server for this resource.

429 Too Many Request

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

DELETE /rest/v1/targetfilters/{targetFilterQueryId}

Implementation Notes

Handles the DELETE request of deleting a target filter query within SP. Required permission: DELETE_TARGET

Deleting a target

CURL

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

Request URL

DELETE /rest/v1/targetfilters/6 HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetFilterQueryId

The technical identifier 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/targetfilters/{targetFilterQueryId}

Implementation Notes

Handles the GET request of retrieving a single target filter query within SP. Required permission: READ_TARGET

Get single target

CURL

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

Request URL

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

Request path parameter

Parameter Description

targetFilterQueryId

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

query

String

target filter query expression

autoAssignDistributionSet

Number

Auto assign distribution set id

autoAssignActionType

String

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

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

autoAssignWeight

Number

Weight of the resulting Actions

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

createdBy

String

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

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

lastModifiedBy

String

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

_links.autoAssignDS

Object

Link to manage the auto assign distribution set

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287364281,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287364294,
  "name" : "filter1",
  "query" : "name==*",
  "autoAssignDistributionSet" : 3,
  "autoAssignActionType" : "forced",
  "autoAssignWeight" : null,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/5"
    },
    "autoAssignDS" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/5/autoAssignDS"
    }
  },
  "id" : 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.

429 Too Many Request

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

PUT /rest/v1/targetfilters/{targetFilterQueryId}

Implementation Notes

Handles the PUT request of updating a target filter query within SP. Required permission: UPDATE_TARGET

Update a target

Curl

$ curl 'https://management-api.host.com/rest/v1/targetfilters/4' -i -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "query" : "attribute.hwRevision==2",
  "name" : "newFilterName"
}'

Request URL

PUT /rest/v1/targetfilters/4 HTTP/1.1
Content-Type: application/json
Content-Length: 69
Host: management-api.host.com

{
  "query" : "attribute.hwRevision==2",
  "name" : "newFilterName"
}

Request path parameter

Parameter Description

targetFilterQueryId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

name

String

The name of the entity

query

String

target filter query expression

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

query

String

target filter query expression

autoAssignDistributionSet

Number

Auto assign distribution set id

autoAssignActionType

String

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

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

autoAssignWeight

Number

Weight of the resulting Actions

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

createdBy

String

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

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

lastModifiedBy

String

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

_links.autoAssignDS

Object

Link to manage the auto assign distribution set

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287363890,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287363910,
  "name" : "newFilterName",
  "query" : "attribute.hwRevision==2",
  "autoAssignDistributionSet" : null,
  "autoAssignActionType" : null,
  "autoAssignWeight" : null,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/4"
    },
    "autoAssignDS" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/4/autoAssignDS"
    }
  },
  "id" : 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

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/targetfilters/{targetFilterQueryId}/autoAssignDS

Implementation Notes

Handles the GET request of retrieving the auto assign distribution set. Required permission: READ_TARGET

Get auto assign distribution set

Curl

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

Request URL

GET /rest/v1/targetfilters/8/autoAssignDS HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetFilterQueryId

The technical identifier of the entity

Response (Status 200)

Response fields

Path Type Description Allowed Values

id

Number

The technical identifier of the entity

name

String

The name of the entity

description

String

The description of the entity

createdBy

String

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

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

lastModifiedBy

String

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

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

type

String

The type of the distribution set.

requiredMigrationStep

Boolean

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

complete

Boolean

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

deleted

Boolean

Deleted flag, used for soft deleted entities

version

String

Package version.

_links.type

Object

The type of the distribution set.

_links.metadata

Object

List of metadata.

_links.modules

Object

List of software modules.

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287365342,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287365350,
  "name" : "DS",
  "description" : "The descption of the distribution set.",
  "version" : "1.0",
  "modules" : [ {
    "createdBy" : "bumlux",
    "createdAt" : 1629287365261,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287365473,
    "name" : "application",
    "description" : "Description of the software module",
    "version" : "1.0.60",
    "type" : "application",
    "vendor" : "vendor Limited, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/13"
      }
    },
    "id" : 13
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287365292,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287365523,
    "name" : "app runtime",
    "description" : "Description of the software module",
    "version" : "1.0.21",
    "type" : "runtime",
    "vendor" : "vendor GmbH, Stuttgart, Germany",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/14"
      }
    },
    "id" : 14
  }, {
    "createdBy" : "bumlux",
    "createdAt" : 1629287365301,
    "lastModifiedBy" : "bumlux",
    "lastModifiedAt" : 1629287365589,
    "name" : "Firmware",
    "description" : "Description of the software module",
    "version" : "1.0.29",
    "type" : "os",
    "vendor" : "vendor Limited Inc, California",
    "deleted" : false,
    "_links" : {
      "self" : {
        "href" : "https://management-api.host.com/rest/v1/softwaremodules/15"
      }
    },
    "id" : 15
  } ],
  "requiredMigrationStep" : false,
  "type" : "test_default_ds_type",
  "complete" : true,
  "deleted" : false,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/5"
    },
    "modules" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/5/assignedSM?offset=0&limit=50{&sort}",
      "templated" : true
    },
    "type" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsettypes/36"
    },
    "metadata" : {
      "href" : "https://management-api.host.com/rest/v1/distributionsets/5/metadata?offset=0&limit=50{&sort,q}",
      "templated" : true
    }
  },
  "id" : 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

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/targetfilters/{targetFilterQueryId}/autoAssignDS

Implementation Notes

Handles the POST request of setting the auto assign distribution set for a target filter query. Required permissions: UPDATE_TARGET and READ_REPOSITORY

Set auto assign distribution set

Curl

$ curl 'https://management-api.host.com/rest/v1/targetfilters/7/autoAssignDS' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "weight" : 200,
  "id" : 4,
  "type" : "soft"
}'

Request URL

POST /rest/v1/targetfilters/7/autoAssignDS HTTP/1.1
Content-Type: application/json
Content-Length: 51
Host: management-api.host.com

{
  "weight" : 200,
  "id" : 4,
  "type" : "soft"
}

Request path parameter

Parameter Description

targetFilterQueryId

The technical identifier of the entity

Request fields

Path Type Description Allowed Values Mandatory

id

Number

Id of the distribution set.

X

type

String

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

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

weight

Number

Weight of the resulting Actions

0 - 1000

when multi-assignment is enabled

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

query

String

target filter query expression

autoAssignDistributionSet

Number

Auto assign distribution set id

autoAssignActionType

String

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

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

autoAssignWeight

Number

Weight of the resulting Actions

createdAt

Number

Entity was originally created at (timestamp UTC in milliseconds)

createdBy

String

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

lastModifiedAt

Number

Entity was last modified at (timestamp UTC in milliseconds)

lastModifiedBy

String

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

_links.autoAssignDS

Object

Link to manage the auto assign distribution set

Response example

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

{
  "createdBy" : "bumlux",
  "createdAt" : 1629287364761,
  "lastModifiedBy" : "bumlux",
  "lastModifiedAt" : 1629287365020,
  "name" : "filter1",
  "query" : "name==*",
  "autoAssignDistributionSet" : 4,
  "autoAssignActionType" : "soft",
  "autoAssignWeight" : 200,
  "_links" : {
    "self" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/7"
    },
    "autoAssignDS" : {
      "href" : "https://management-api.host.com/rest/v1/targetfilters/7/autoAssignDS"
    }
  },
  "id" : 7
}

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.

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/targetfilters/{targetFilterQueryId}/autoAssignDS

Implementation Notes

Removes the auto assign distribution set from the target filter query. Required permission: UPDATE_TARGET

Removing the auto assign distribution set

Curl

$ curl 'https://management-api.host.com/rest/v1/targetfilters/1/autoAssignDS' -i -X DELETE

Request URL

DELETE /rest/v1/targetfilters/1/autoAssignDS HTTP/1.1
Host: management-api.host.com

Request path parameter

Parameter Description

targetFilterQueryId

The technical identifier of the entity

Response (Status 204)

Response example

HTTP/1.1 204 No Content

Error responses

HTTP Status Code Reason Response Model

400 Bad Request

Bad Request - e.g. invalid parameters

401 Unauthorized

The request requires user authentication.

403 Forbidden

Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies.

See Error body

404 Not Found

Not Found Target.

See Error body

405 Method Not Allowed

The http request method is not allowed on the resource.

406 Not Acceptable

In case accept header is specified and not application/json.

429 Too Many Request

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

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