We are launching a public preview of the capability to have tags applied to your APIs and operations. This enables the organization of large lists – both in terms of management and presentation on the developer portal.
Tags can be applied during manual editing or they can be imported as part of an OpenAPI Specification. When exporting, only tags that are set on operations will be part of the specification, as tags on the API are not supported by the standard.
Setting and editing tags on an API
- To begin, first open your API Management service in the Azure portal.
- Then, open the APIs page and select the API you want to modify.
- Under the Settings tab you will find a new field called “Tags”.
- Enter the tags you would like applied here.
- As you type the system will search and allow you to select pre-existing tags or alternatively create a new one.
Setting and editing tags on operations
- Assuming you already have the API containing the operations open, select the operation you would like to modify.
- Open the frontend editor by clicking on the Pencil icon in the Frontend box.
- In the main editing area above the tabs you will find a new field called “Tags”.
- Enter the tags you would like to add – you will have the option to choose existing ones or create new tags as in the API editor.
Editing tag definitions
API Management stores the tags for all your APIs centrally. This allows you to pre-create tags before they are applied anywhere and also to edit tags centrally. Right now, no tag metadata is supported, but we plan to add that as well.
Creating a tag
- From the Azure portal view of your API Management service select Tags from the menu.
- Click Add
- Provide a display name for your tag – this is what will be seen as the tag applied to APIs or operations
- Use the default or provide a separate name – this is the Azure Resource Manager (ARM) identifier of the tag. It will not be exported in OpenAPI specification or visible in any form on the developer portal, but it is used to identify with which tag a given API or operation is tagged with.
- Click Create
Renaming a tag
Renaming a tag from the central tag repository will ensure that all resources tagged with it (APIs, operations, etc.) get the new tag as they are linked to the tag by an identifier (the ARM name) and not the tag's display name. In other words, if API1 and API2 are tagged with tag1 and you rename it centrally to tagA then both API1 and API2 will now be tagged with tagA.
- Select a tag from within the Tags page of your API Management service
- Modify the display name as needed
- Click Save
Filtering the list of APIs and operations based on tags in the Azure portal
Both the list of APIs and operations now allow you to filter the list by one or more tags in addition to searching for keywords. At the top of the list below the search box there is now a filter by tag box.
- Select the filter box (background text: “Add tags to query”)
- Pick a tag from the list or type in a tag to filter
Filtering the list of APIs and operations based on tags in the Developer portal
Filtering is now available on the developer portal as well. A new combination search, filter and view selector control will only appear for APIs that utilize tags.
It's a two-state control – in collapsed state it shows the search query and the tags by which filtration is to happen. It also shows a view selector.
- Select the search/filter control to expand it and edit the query
- Select the filter box and select a tag to filter on
Group the list of APIs and operations based on tags in the Developer portal
Lists can now be rendered in two formats:
- A flat list regardless of what tags are applied to a given list item
- A grouped list where items are grouped together based on what tag is assigned to them – a list for each tag
