Tags

Tags are labels you can apply to your APIs in 42Crunch Platform to group them together. While this sounds a bit like what API collections do, there are crucial differences:

• Tags are applied to individual, not all, APIs in an API collection. You can have both tagged and untagged APIs in the same API collection, and APIs in a collection could have different set of tags applied to them.
• Tags are not limited to a single API collection but can group APIs from multiple collections.

So while API collections form physical groups of APIs, tags form virtual groups of APIs.

You can tag APIs in your own API collections and in any collections that you have been given Read/Write access to. You cannot tag or untag APIs that you only have Read-Only access to.

Tags are also the mechanism for applying things like security quality gates (SQGs) or customization rules to your APIs. When you define your customizations, you also define the tags that go with those. Then, to apply the SQGs or customization rules to your APIs, you tag each API with the corresponding tag. You can check which rule or SQG each tag applies.

Tags and tag categories

Tags themselves are grouped into meaningful units using categories, and each tag must always have a category it belongs. In reality, tags therefore consist of category:tag value pairs.

To get you started, every organization gets two tag categories out of the box: one for customization rules and another for SQGs. You can edit these categories if you like and add more categories anytime as needed.

Only organization administrators can manage tags and categories in their organization.

What kind of categories and tags — or how many — you need fully depends on your organization, your line of business, what kind of APIs you have, and how you plan to use tags. There are many other purposes than just applying different rules and acceptance criteria to APIs that you could potentially use tags for, so think what makes sense for you and be creative.

We recommend putting things like SQGs and customization rules in categories dedicated to just them, so that it is easy to find the related tags.

Tags within a category must be unique, but you can use same tag names in different categories. For example, you might want to have tags to apply different SQGs to your internal and external APIs and in your development, testing, and production environments. In this case, you could create categories called Internal and External which could both contain tags Dev, Test and Prod.

This would give you the following category:tag value pairs:

Category "Internal"	Category "External"
Internal:Dev	External:Dev
Internal:Test	External:Test
Internal:Prod	External:Prod

Depending on how you decide to use tags, you might want to enforce all APIs to have a certain tag. For example, you might want to ensure that your APIs are tagged for the service or application they relate to. In this case, you could create a category called, for example, Application and add a tag for each of your applications to it. You could then use a customization rule to enforce that category as mandatory for all APIs. See Customizations for mandatory tag categories.

Category settings

When creating new categories, organization administrators can select settings to control how those categories behave, such as can users add new tags to the category as they apply tags to the API, who can tag or untag APIs, or how many tags from a category can be applied to an API.

By default, only organization administrators can add new tags to categories, but this might not always be ideal. In some categories, you might want to allow users to create new tags as they need them. For this, you can allow other users to add new tags to a category when they apply tags to their APIs.

The users still cannot delete any tags, nor can they add new categories to your organization.

This setting applies to all users in your organization. If you switch this option on in a category, anyone in your organization can add new tags to when they apply tags to their APIs.

You can also designate some tags to be managed fully by organization administrators, including applying them to APIs. All users can see these admin-only tags, but it is only organization administrators who can apply or remove these tags from APIs. Regular users cannot choose when to use or not to use them. This category setting is particularly useful for tags that enforce organization-wide policies, such as SQGs or mandatory categories.

By default, you can only apply one tag per category to an API, but sometimes you might want to apply multiple tags from a single category. For example, you might have several teams that use the same APIs and want to reflect this in your tags. In this case, you could create the category Teams and allow applying multiple tags from that particular category. You could then add a tag for each team, and then apply the ones you want to the APIs as needed.

Just like what kind of tags and categories you need, when to allow applying multiple tags from a category also is highly subjective to each organization and depends on multiple things like your APIs, your company structure, your teams, so use your judgment and enable it when it makes sense to you. Resorting to having just one category to contain all your tags and allowing applying multiple tags from it as a labor saving shortcut might prove to be false economy down the line.

If you decide to allow applying multiple tags from a category, you cannot change your mind and switch it off later. Users might already have applied multiple tags from the category to their APIs and it would not be possible to automatically decide how to roll back in these cases. It is best to delete the category and start again, this time not allowing multiple tags. You can always decide to allow multiple tags later but once you do, you cannot change back.

The category settings are independent from each other, and you can set any combination of them. For example, you could allow users to create tags to a category, but restrict applying and removing those tags to organizations administrators only.