Tagging datastreams in Management API

Introduction

What is a datastream tag?

A tag is a short label, such as prod or daily, that you attach to datastreams to group them, for example to select them in an external orchestrator.

Which workspace does a tag belong to?

Every tag belongs to exactly one workspace. Its name is unique within that workspace, ignoring case. The same name in another workspace, including a parent or child workspace, is a separate tag.

Which tags can a datastream carry?

A datastream only carries tags of its own workspace. Anyone who can see the datastream can see its tags.

What happens when a datastream is copied or moved?

Its tags follow it. In another workspace, each tag is matched by name to a tag of that workspace, and created there if it does not exist yet.

Where do tag changes appear?

Adding, removing, and deleting tags appears in the History tab of each affected datastream, with the tag names before and after the change.

Prerequisites

Obtain a Management API key with the appropriate scope:

• datastream: read to list tags, read the tags of datastreams, and filter datastreams by tag.

• datastream: write to create, rename, and delete tags, and to add them to or remove them from datastreams.

An existing key may not have these scopes, even if it works with the legacy endpoints. For how to check a key and what to do if it lacks them, see Authentication and scopes in v1.

The key can only see and change tags of the workspaces it has access to. For more information, see Authorizing to Management API.

Limitations

Requests that exceed the per-request list limits return an HTTP 422 error. A bulk request that matches more than 500 datastreams through its query parameters returns an HTTP 400 error.

Creating a tag

To create a tag, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/
   

2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following parameters:

   Scroll horizontally to see the full table.

   Parameter	Required	Description
   workspace_id	Yes	The UUID of the workspace that owns the tag.
   name	Yes	The tag name. Up to 25 characters. Leading and trailing spaces are removed.

5. Send the request.

As a result, Adverity creates the tag and returns it with HTTP 201. If the workspace already has a tag with the same name, ignoring case, the response is HTTP 409 and contains the existing tag in tag.

The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/datastream-tags/' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"workspace_id": "{{WORKSPACE_ID}}", "name": "prod"}'

A tag in the response contains the following fields:

The response to a create request also contains same_name_in_ancestor_workspaces: the parent workspaces, among those the key can see, that already have a tag with this name. Those are separate tags.

Listing tags

To list tags, follow these steps:

1. Create a GET request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/
   

2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

3. (Optional) To list the tags of specific workspaces, add the workspace_id query parameter. Repeat it for each workspace.

4. (Optional) To find a tag by its exact name, ignoring case, add the name query parameter.

5. Send the request.

As a result, you obtain the tags of the workspaces the key can see, sorted by name and paginated with the page and page_size query parameters.

To retrieve one tag, create a GET request to https://{{INSTANCE}}/api/v1/datastream-tags/{{TAG_ID}}/.

Renaming a tag

To rename a tag, follow these steps:

1. Create a PATCH request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/{{TAG_ID}}/
   

2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include name with the new tag name.

5. Send the request.

As a result, every datastream that carries the tag shows the new name. Earlier entries in the History tab keep the old name. If another tag of the same workspace has the new name, the response is HTTP 409. Changing only the case of the name is allowed. The workspace of a tag cannot change.

Deleting a tag

To delete a tag, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastream-tags/{{TAG_ID}}/
   

2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

3. Send the request.

As a result, Adverity deletes the tag and removes it from every datastream that carried it. The response field removed_from_datastreams contains the number of datastreams the tag was removed from.

Adding tags to datastreams

To add tags to up to 500 datastreams in one request, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastreams/tags/
   

2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include the following parameters:

   Scroll horizontally to see the full table.

   Parameter	Required	Description
   tags	Yes	Up to 50 tag names or tag UUIDs. A name is looked up in the workspace of each datastream, ignoring case. A UUID applies only to the datastreams of its own workspace.
   datastream_ids	No	Up to 500 datastream UUIDs.

5. (Optional) To target datastreams by their properties, add the query parameters of the datastream list, such as workspace_id or tag. For all of them, see Listing datastreams in Management API. They are combined with datastream_ids. A request needs datastream_ids, a query parameter, or both.

6. (Optional) To create tag names that a workspace does not have yet, add the create_missing=true query parameter.

7. Send the request.

As a result, each targeted datastream gets every tag that applies to it. The response contains the following fields:

If one of the tag UUIDs does not exist or the key cannot see it, for example because the tag was deleted, the whole request fails with HTTP 400 and no datastream is changed.

A datastream gets either all of the tags that apply to it or none of them. It is skipped for one of the following reasons, and the other datastreams are still tagged:

Sending the same request again changes nothing.

The cURL request example is the following:

curl --location --request POST 'https://{{INSTANCE}}/api/v1/datastreams/tags/?create_missing=true' \
--header 'Authorization: Bearer {{KEY}}' \
--header 'Content-Type: application/json' \
--data '{"tags": ["prod", "daily"], "datastream_ids": ["{{DATASTREAM_ID_1}}", "{{DATASTREAM_ID_2}}"]}'

Removing tags from datastreams

To remove tags from up to 500 datastreams in one request, follow these steps:

1. Create a DELETE request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastreams/tags/
   

2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include tags and datastream_ids as described in Adding tags to datastreams. The same query parameters apply.

5. Send the request.

As a result, the tags are removed from the targeted datastreams that carry them. The response field unassigned_datastream_ids lists the targeted datastreams, and skipped lists the ones that were not_found. As with adding, a tag UUID that does not exist or that the key cannot see fails the whole request with HTTP 400. A remove request never creates tags, and sending it again changes nothing.

Reading the tags of datastreams

To read the tags of up to 500 datastreams in one request, follow these steps:

1. Create a POST request to the following endpoint:

   https://{{INSTANCE}}/api/v1/datastreams/tags/query/
   

2. In the HTTP request header, include the Authorization: Bearer {{KEY}} parameter.

3. In the HTTP request header, include the parameter Content-Type with value application/json.

4. In the HTTP request body, include datastream_ids with up to 500 datastream UUIDs.

5. Send the request.

As a result, you obtain one item per datastream the key can see, in the order of the request, each with its datastream_id and a tags list. Unknown UUIDs are left out. This request only reads; it uses POST because the list of UUIDs does not fit into a URL.

Filtering datastreams by tag

Each item of GET https://{{INSTANCE}}/api/v1/datastreams/ contains a tags list with the id and name of each tag. To list only datastreams with certain tags, add the following query parameters:

You can combine them with the other query parameters of the list. For all of them, see Listing datastreams in Management API.

The cURL request example is the following:

curl --location --request GET 'https://{{INSTANCE}}/api/v1/datastreams/?tag=prod&tag=daily&tag_match=all' \
--header 'Authorization: Bearer {{KEY}}'

The same query parameters also target the bulk datastream update, the smart schedule update, and the custom monitor assignment requests. For more information, see Managing pulling mode and smart schedule in Management API and Bulk assigning custom monitors in Management API.