API Limitations
Add Members API
Maximum of 100,000 tag members supported efficiently.
- Each batch can include up to 2,000 tag members. If a tag is supposed to have 20,000 members, 10 sequential requests need to be sent, one after another.
Adding more than this can cause delays in tag-related operations.
Optimization for handling larger volumes is currently in progress.
Get Members API
Recommended for tags with fewer than 100,000 members.
Use cautiously with larger tags to avoid performance issues.
API endpoints
SAT token requirements
Client should have following SAT capabilities:
"x1:coast:cmtagds:assign",
"x1:coast:cmtagds:read",
"x1:coast:cmtagds:unassign",
"x1:coast:xconf:read",
"x1:coast:xconf:read:maclist",
"x1:coast:xconf:write",
"x1:coast:xconf:write:maclist",
Get tag by id
Returns representation of XConf tag by provided tag id
GET /taggingService/tags/{id}
Headers:
Accept = application/json
Content-Type = application/json
Authorization = Bearer {SAT token}
Response: 200 OK, 404 NOT FOUND
Response Body:
{
"id": "test:tag:demotag",
"description": "",
"members": [
"A2:A2:A2:A2:B2:B2"
],
"updated": 1711651165855
}
Delete Tag
Removes tag from Redis based in-memory service first and in case of success from XConf
DELETE /taggingService/tags/{id}
Headers:
Accept = application/json
Content-Type = application/json
Authorization = Bearer {SAT token}
Response: 204 NO CONTENT, 404 NOT FOUND
Add members to tag
Adds new members to the tag. If tag does not exist – new tag is created in XConf. By default XConf does tag member normalization: whitespaces are trimmed, string data is set to upper case.
PUT /taggingService/tags/{tag}/members
Headers:
Accept = application/json
Content-Type = application/json
Authorization = Bearer {SAT token}
Request Body - list of members:
["A1:A1:A1:A1:B1:B1", "A2:A2:A2:A2:B2:B2"]
Response: 200 OK status.
Response Body - XConf tag entity with added members:
{
"id": "test:tag:demotag",
"description": "",
"members": [
"A1:A1:A1:A1:B1:B1",
"A2:A2:A2:A2:B2:B2"
],
"updated": 1711651165855
}
Remove members from tag
Removes members from the tag. If all members are removed, the tag is automatically deleted.
DELETE /taggingService/tags/{tag}/members
Headers:
Accept = application/json
Content-Type = application/json
Authorization = Bearer {SAT token}
Request Body - list of members:
["A1:A1:A1:A1:B1:B1", "A2:A2:A2:A2:B2:B2"]
Response:404 NOT FOUND, 204 NO CONTENT status.
Remove member from tag
Removes member record from Redis based in-memory service first, in case of success removes tag member from XConf. Remove API takes non normalized data, normalization is done by XConf.
DELETE /taggingService/tags/{tag}/members/{member}
Headers:
Accept = application/json
Content-Type = application/json
Authorization = Bearer {SAT token}
Response: 204 NO CONTENT status.
Get tag members
GET /taggingService/tags/{tag}/members
Headers:
Accept = application/json
Content-Type = application/json
Authorization = Bearer {SAT token}
Response: list of all tag members, array of strings, 200 OK status.
Response Body:
1. Create New Firmware Rule with the tag as the condition using EXISTS operation.
2. Add needed MAC address or any other parameters to the tag, use "Add member to tag" API
curl --location --request PUT 'http://<xconf-admin-url>/taggingService/tags/xconf:tag:usage:demo/members' \
--header 'Authorization: Bearer <SAT token>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '["BB:BB:BB:BB:BB:BB"]'
3. Trigger /swu/xconf/ API to evaluate the rules, make sure that tag member from 2. is present as in the request parameters of /swu/xconf/ query:
curl --location 'http://<xconf-url>/xconf/swu/stb?model=TESTMODEL&eStbMac=BB%3ABB%3ABB%3ABB%3ABB%3ABB&firmwareVersion=TEST_VERSION'
{
"firmwareDownloadProtocol": "tftp",
"firmwareFilename": "filename.t",
"firmwareVersion": "TEST_VERSION_TAGGING_USAGE",
"mandatoryUpdate": false,
"rebootImmediately": false
}
