- GET /rest/v1/targettags
- GET /rest/v1/targettags/{targetTagId}
- POST /rest/v1/targettags
- PUT /rest/v1/targettags/{targetTagId}
- DELETE /rest/v1/targettags/{targetTagId}
- GET /rest/v1/targettags/{targetTagId}/assigned
- POST /rest/v1/targettags/{targetTagId}/assigned/toggleTagAssignment
- POST /rest/v1/targettags/{targetTagId}/assigned
- DELETE /rest/v1/targettags/{targetTagId}/assigned/{controllerId}
- Additional content
GET /rest/v1/targettags
Implementation notes
Handles the GET request of retrieving all target tags.
Get paged list of target tags
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags' -i -X GET
Request URL
A GET
request is used to access the target tags
GET /rest/v1/targettags HTTP/1.1
Host: management-api.host.com
Request query parameter
Parameter | Description |
---|---|
|
The maximum number of entries in a page (default is 50). |
|
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. |
|
The paging offset (default is 0). |
|
Query fields based on the Feed Item Query Language (FIQL). See Entity Definitions for available fields. |
Request parameter example
GET /rest/v1/targettags?limit=10&sort=name:ASC&offset=0&q=name%3D%3DtargetTag HTTP/1.1
Host: management-api.host.com
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
size |
Number |
Current page size |
|
total |
Number |
Total number of elements |
|
content |
Array |
List of provisioning targets. |
|
content[].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[].colour |
String |
The colour of the entity |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 418
{
"content" : [ {
"createdBy" : "bumlux",
"createdAt" : 1564644748713,
"lastModifiedBy" : "bumlux",
"lastModifiedAt" : 1564644748715,
"name" : "targetTag",
"description" : "My name is targetTag",
"colour" : "default",
"_links" : {
"self" : {
"href" : "https://management-api.host.com/rest/v1/targettags/6"
}
},
"id" : 6
} ],
"total" : 1,
"size" : 1
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /rest/v1/targettags/{targetTagId}
Implementation notes
Handles the GET request of retrieving a single target tag.
Get a single target tag
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags/3' -i -X GET
Request URL
A GET
request is used to access the target tag
GET /rest/v1/targettags/3 HTTP/1.1
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
targetTagId |
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) |
|
colour |
String |
The colour of the entity |
|
_links.assignedTargets |
Object |
Links to assigned targets. |
Response example
HTTP/1.1 200 OK
Content-Length: 504
Content-Type: application/hal+json;charset=UTF-8
{
"createdBy" : "bumlux",
"createdAt" : 1564644733343,
"lastModifiedBy" : "bumlux",
"lastModifiedAt" : 1564644733346,
"name" : "targetTag",
"description" : "My name is targetTag",
"colour" : "default",
"_links" : {
"self" : {
"href" : "https://management-api.host.com/rest/v1/targettags/3"
},
"assignedTargets" : {
"href" : "https://management-api.host.com/rest/v1/targettags/3/assigned?offset=0&limit=50{&sort,q}",
"templated" : true
}
},
"id" : 3
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /rest/v1/targettags
Implementation Notes
Handles the POST request of creating new target tag. The request body must always be a list of target tags.
Create list of target tags
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '[ {
"colour" : "red",
"name" : "target tag",
"description" : "target tag description"
} ]'
Request URL
POST /rest/v1/targettags HTTP/1.1
Content-Length: 95
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com
[ {
"colour" : "red",
"name" : "target tag",
"description" : "target tag description"
} ]
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
[]name |
String |
The name of the entity |
X |
|
[]description |
String |
The description of the entity |
X |
|
[]colour |
String |
The colour of the entity |
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 |
|
[]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) |
|
[]colour |
String |
The colour of the entity |
Response example
HTTP/1.1 201 Created
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 342
[ {
"createdBy" : "bumlux",
"createdAt" : 1564644722903,
"lastModifiedBy" : "bumlux",
"lastModifiedAt" : 1564644722903,
"name" : "target tag",
"description" : "target tag description",
"colour" : "red",
"_links" : {
"self" : {
"href" : "https://management-api.host.com/rest/v1/targettags/1"
}
},
"id" : 1
} ]
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
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 |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
PUT /rest/v1/targettags/{targetTagId}
Implementation Notes
Handles the PUT request of updating a target tag.
Update a target tag
Curl
$ curl 'https://management-api.host.com/rest/v1/targettags/4' -i -X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"colour" : "red",
"name" : "target tag",
"description" : "target tag description"
}'
Request URL
PUT /rest/v1/targettags/4 HTTP/1.1
Content-Length: 91
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com
{
"colour" : "red",
"name" : "target tag",
"description" : "target tag description"
}
Request path parameter
Parameter | Description |
---|---|
targetTagId |
The technical identifier of the entity |
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
name |
String |
The name of the entity |
X |
|
description |
String |
The description of the entity |
X |
|
colour |
String |
The colour 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) |
|
colour |
String |
The colour of the entity |
|
_links.assignedTargets |
Object |
Links to assigned targets. |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 503
{
"createdBy" : "bumlux",
"createdAt" : 1564644738448,
"lastModifiedBy" : "bumlux",
"lastModifiedAt" : 1564644738454,
"name" : "target tag",
"description" : "target tag description",
"colour" : "red",
"_links" : {
"self" : {
"href" : "https://management-api.host.com/rest/v1/targettags/4"
},
"assignedTargets" : {
"href" : "https://management-api.host.com/rest/v1/targettags/4/assigned?offset=0&limit=50{&sort,q}",
"templated" : true
}
},
"id" : 4
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
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 |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
DELETE /rest/v1/targettags/{targetTagId}
Implementation Notes
Handles the DELETE request of deleting a single target tag.
Deleting a target tag
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags/5' -i -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Request URL
DELETE /rest/v1/targettags/5 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
targetTagId |
The technical identifier of the entity |
Response (Status 200)
Response example
HTTP/1.1 200 OK
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
GET /rest/v1/targettags/{targetTagId}/assigned
Implementation Notes
Handles the GET request of retrieving a list of assigned targets.
Get a list of assigned targets
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags/2/assigned' -i -X GET \
-H 'Content-Type: application/json;charset=UTF-8'
Request URL
GET /rest/v1/targettags/2/assigned HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
targetTagId |
The technical identifier of the entity |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
content[].createdBy |
String |
Entity was originally created by User, AMQP-Controller, anonymous etc.) |
|
content[].address |
String |
The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp. |
|
content[].createdAt |
Number |
Entity was originally created at (timestamp UTC in milliseconds) |
|
content[].name |
String |
The name of the entity |
|
content[].description |
String |
The description of the entity |
|
content[].controllerId |
String |
The technical identifier of the entity |
|
content[].updateStatus |
enum |
Current update status of the target. |
['error', 'in_sync', 'pending', 'registered', 'unknown'] |
content[].securityToken |
String |
Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings. |
|
content[].requestAttributes |
Boolean |
Request re-transmission of target attributes. |
|
content[].installedAt |
Number |
Installation time of current installed DistributionSet. |
|
content[].lastModifiedAt |
Number |
Entity was last modified at (timestamp UTC in milliseconds) |
|
content[].lastModifiedBy |
String |
Entity was last modified by User, AMQP-Controller, anonymous etc.) |
|
content[].ipAddress |
String |
Last known IP address of the target. Only presented if IP address of the target itself is known (connected directly through DDI API). |
|
content[].lastControllerRequestAt |
Number |
Last time where the target polled the server, same as pollStatus.lastRequestAt. |
|
size |
Number |
Current page size |
|
total |
Number |
Total number of elements |
|
content |
Array |
List of provisioning targets. |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 684
{
"content" : [ {
"createdBy" : "bumlux",
"createdAt" : 1564644728095,
"lastModifiedBy" : "bumlux",
"lastModifiedAt" : 1564644728237,
"name" : "Target1",
"description" : "My name is Target1",
"controllerId" : "Target1",
"updateStatus" : "in_sync",
"lastControllerRequestAt" : 1564644728050,
"installedAt" : 1564644728220,
"ipAddress" : "192.168.0.1",
"address" : "http://192.168.0.1",
"securityToken" : "deaddfdf8e1c7640b777b070ad056f37",
"requestAttributes" : true,
"_links" : {
"self" : {
"href" : "https://management-api.host.com/rest/v1/targets/Target1"
}
}
} ],
"total" : 1,
"size" : 1
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /rest/v1/targettags/{targetTagId}/assigned/toggleTagAssignment
Implementation Notes
Handles the POST request of toogle target assignment. The request body must always be a list of controller ids.
Toogle target assignment
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags/10/assigned/toggleTagAssignment' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '[ {
"controllerId" : "Target1"
} ]'
Request URL
POST /rest/v1/targettags/10/assigned/toggleTagAssignment HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 36
Host: management-api.host.com
[ {
"controllerId" : "Target1"
} ]
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
[]controllerId |
String |
The technical identifier of the entity |
X |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
assignedTargets |
Array[Object] |
Assigned targets. |
|
unassignedTargets |
Array[Object] |
Unassigned targets. |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 773
{
"assignedTargets" : [ {
"createdBy" : "bumlux",
"createdAt" : 1564644769340,
"lastModifiedBy" : "bumlux",
"lastModifiedAt" : 1564644769375,
"name" : "Target1",
"description" : "My name is Target1",
"controllerId" : "Target1",
"updateStatus" : "pending",
"lastControllerRequestAt" : 1564644769339,
"ipAddress" : "192.168.0.1",
"address" : "http://192.168.0.1",
"securityToken" : "13fcd5073f8c9f89690c4e01ec6c799b",
"requestAttributes" : true,
"links" : [ {
"rel" : "self",
"href" : "https://management-api.host.com/rest/v1/targets/Target1",
"hreflang" : null,
"media" : null,
"title" : null,
"type" : null,
"deprecation" : null
} ]
} ],
"unassignedTargets" : [ ]
}
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
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 |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
POST /rest/v1/targettags/{targetTagId}/assigned
Implementation Notes
Handles the POST request of target assignment. Already assigned target will be ignored.
Target assignment
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags/8/assigned' -i -X POST \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '[ {
"controllerId" : "Target1"
} ]'
Request URL
POST /rest/v1/targettags/8/assigned HTTP/1.1
Content-Type: application/json;charset=UTF-8
Content-Length: 36
Host: management-api.host.com
[ {
"controllerId" : "Target1"
} ]
Request fields
Path | Type | Description | Allowed Values | Mandatory |
---|---|---|---|---|
[]controllerId |
String |
The technical identifier of the entity |
X |
Response (Status 200)
Response fields
Path | Type | Description | Allowed Values |
---|---|---|---|
[]createdBy |
String |
Entity was originally created by User, AMQP-Controller, anonymous etc.) |
|
[]address |
String |
The last known address URI of the target. Includes information of the target is connected either directly (DDI) through HTTP or indirectly (DMF) through amqp. |
|
[]createdAt |
Number |
Entity was originally created at (timestamp UTC in milliseconds) |
|
[]name |
String |
The name of the entity |
|
[]description |
String |
The description of the entity |
|
[]controllerId |
String |
The technical identifier of the entity |
|
[]updateStatus |
enum |
Current update status of the target. |
['error', 'in_sync', 'pending', 'registered', 'unknown'] |
[]securityToken |
String |
Pre-Shared key that allows targets to authenticate at Direct Device Integration API if enabled in the tenant settings. |
|
[]requestAttributes |
Boolean |
Request re-transmission of target attributes. |
|
[]installedAt |
Number |
Installation time of current installed DistributionSet. |
|
[]lastModifiedAt |
Number |
Entity was last modified at (timestamp UTC in milliseconds) |
|
[]lastModifiedBy |
String |
Entity was last modified by User, AMQP-Controller, anonymous etc.) |
|
[]ipAddress |
String |
Last known IP address of the target. Only presented if IP address of the target itself is known (connected directly through DDI API). |
|
[]lastControllerRequestAt |
Number |
Last time where the target polled the server, same as pollStatus.lastRequestAt. |
Response example
HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8
Content-Length: 597
[ {
"createdBy" : "bumlux",
"createdAt" : 1564644758974,
"lastModifiedBy" : "bumlux",
"lastModifiedAt" : 1564644758999,
"name" : "Target1",
"description" : "My name is Target1",
"controllerId" : "Target1",
"updateStatus" : "in_sync",
"lastControllerRequestAt" : 1564644758973,
"installedAt" : 1564644758989,
"ipAddress" : "192.168.0.1",
"address" : "http://192.168.0.1",
"securityToken" : "7e96e5a9f69817afa4a289b0679eeadf",
"requestAttributes" : true,
"_links" : {
"self" : {
"href" : "https://management-api.host.com/rest/v1/targets/Target1"
}
}
} ]
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
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 |
|
The request was attempt with a media-type which is not supported by the server for this resource. |
|
|
Too many requests. The server will refuse further attempts and the client has to wait another second. |
DELETE /rest/v1/targettags/{targetTagId}/assigned/{controllerId}
Implementation Notes
Handles the DELETE request to unassign the given target.
Unassign a target
CURL
$ curl 'https://management-api.host.com/rest/v1/targettags/7/assigned/targetExist' -i -X DELETE \
-H 'Content-Type: application/json;charset=UTF-8'
Request URL
DELETE /rest/v1/targettags/7/assigned/targetExist HTTP/1.1
Content-Type: application/json;charset=UTF-8
Host: management-api.host.com
Request path parameter
Parameter | Description |
---|---|
targetTagId |
The technical identifier of the entity |
controllerId |
The technical identifier of the entity |
Response (Status 200)
Response example
HTTP/1.1 200 OK
Error responses
HTTP Status Code | Reason | Response Model |
---|---|---|
|
Bad Request - e.g. invalid parameters |
|
|
The request requires user authentication. |
|
|
Insufficient permissions, entity is not allowed to be changed (i.e. read-only) or data volume restriction applies. |
See Error body |
|
Not Found Target. |
See Error body |
|
The http request method is not allowed on the resource. |
|
|
In case accept header is specified and not application/json. |
|
|
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 |