XConf Tagging Service API

 Performance Information

Add Members API

The Add Members API processes member additions in batches, with each batch supporting up to 2,000 members.

Estimated Processing Times

Delete Members API

The Delete Members API also operates in batches of up to 2,000 members per batch.

Estimated Processing Times

API Limitations

Add Members API

• Maximum of 100,000 tag members supported efficiently. 

• 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 XDAS 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 XDAS 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:

[
    "A2:A2:A2:A2:B2:B2"
]

 XConf Rule Configuration with tags

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
}