Tagging your assets

Tags are key:value pairs that act like metadata that help you organize and search your assets.

These tags are instrumental in facilitating resource management, identification, organization, and filtration. By assigning tags, resources can be effectively categorized based on various criteria such as their purpose, ownership, operational environment, or other distinctive characteristics.

A tag is composed of two elements, with the value component being optional:

A Tag Key: This could include terms like 'Utility', 'Department', or 'Project', for instance. It's important to note that tag keys are case sensitive, implying 'Project' and 'project' would represent different tags.
A Tag Value: This could comprise identifiers like '111' or 'prod'. Mirroring the nature of tag keys, tag values are also case sensitive.

In essence, tags serve as an efficient tool to categorize resources. Whether you need to sort them by purpose, owner, environment, or any other defining criteria, asset tags significantly simplify the management and discoverability of your resources.

How to add tags to your assets

There are three ways to add tags:

Through the interface on the portal
Using results api access (see Asset tags section of )
Automatically manage tags when the apis are imported and synchronized using OpenAPI/Swagger file uploads either using the portal ASM setup interface or Results API.

Added tags are recursively propagated to child resources such as individual API operations when applying a tag to the top-level api. When searching for issues results will include issues for all relevant resources in the full stack context.

Efficient Management of Asset Tags through Manual OpenAPI/Swagger Definition File Uploads

Automated Extraction and Import of Tags

Manual management of tags, whether dealt with individually or in bulk, could be a tedious process if done through the portal while automating this process using the results API necessitates writing code and keeping track of asset UUIDs. A more efficient and streamlined alternative is leveraging OpenAPI tags, which eliminates these complexities.

During manual import via API or portal, the OpenAPI (Swagger) specification allows automatic extraction and import of these tags. The tags are then applied to the corresponding assets in the document. This approach offers an efficient, code-free way to manage tags, simplifying automation without needing to track asset UUIDs.

Describing Tags at the root of the document

Consider an openAPI file that includes tags definition at the root of the document as shown below:

openapi: 3.0.0
info:
  title: Sample API
tags:
- name: 'user'
  x-datatheorem-tag-value: 'custom value'
paths: {}

During the upload, these tags are automatically extracted and automatically applied globally to all assets in the document.

x-datatheorem-tag-value in the example above is a custom tag attribute supported by our import API, to define optional tag values.

Describing Tags at the Operation Level

An example of operation level tagging is as follows:

paths:
  /users:
    get:
      tags:
      - 'list-users'
      summary: Lists all users

Operation-level tags are exclusively associated with specific operations within the API document. In this illustration, the 'list-users' tag gets specifically applied to the 'GET /users' operation.

Important Note: The OpenAPI specification does not allow the setting of custom values at the operation level. Instead, it defaults to the value from the root level definition. As a result, only a single unique key-value pair per key within the document is permissible.

Best practices

The recommended best practice involves maintaining an inventory of tagged OpenAPI files and utilizing the results API for their upload. If there's a requirement to update the tags, simply amend the OpenAPI files and re-upload these specification files via the API. This will effectively synchronize the changes across your resources.

Related articles