Skip to main content
System StatusContact Support
VersionOne Community

api/tags

Overview

This endpoint provides read, write, and update access to tags. This endpoint queries for tags, creates tags, and updates tags.

API
URL Form

<Server Base URI>/api/tags/Command/<command>

<Server Base URI>/api/tags/all

<Server Base URI>/api/tags/<tag>

Authentication Application
HTTP Request Verb HTTP GET, HTTP POST
Response Content Type application/json

HTTP Verbs

HTTP GET

GET requests are used to query information, and receive a JSON response.

HTTP POST

POST requests are used to update information.

What are Tags?

First and foremost Tags are values that exist on most BaseAssets.  Tags exist only in the context of the Assets they are added to.  This means adding (and removing) tags for an Asset should be done via rest-1.v1/Data.

As of now Tags have been exposed on the following Assets via the AttributeDefinition TaggedWith

  • Story
  • Defect
  • Test Set
  • Task
  • Test
  • Portfolio Item
  • Regression Test

Adding And Removing Tags from Assets

Below is an example of adding the RMA tag and removing the UX tag from an existing Story.

<Server Base URI>/rest-1.v1/Data/Story/1224

Post Data:

{
    "Attributes": {
        "TaggedWith": {
            "name": "TaggedWith",
            "value": [
                {
                    "idref": "RMA",
                    "act": "add"
                },
                {
                    "idref": "UX",
                    "act": "remove"
                }
            ]
        }
    }
}

Examples of the Tag API : GET

A Single Tag

The following example returns usage information for the specified tag. It will let you know based on your scope visibility the total # of usages of the tag count vs the usage that are visible to your member visibleCount.

<Server Base URI>/api/tags?tag=UX

Response:

{
  "tag": "UX",
  "count": 1,
  "visibleCount": 1
}

All Tags

The following example returns every tag in use in the system with usage information broken down the same as the Single Tag above.

<Server Base URI>/api/tags/all

Response:

{
  "acceptanceTestDetails": {
    "tag": "AcceptanceTestDetails",
    "count": 1,
    "visibleCount": 1
  },
  "acceptanceTestDetails 2": {
    "tag": "AcceptanceTestDetails 2",
    "count": 1,
    "visibleCount": 1
  },
  "acceptanceTestDetails 3": {
    "tag": "AcceptanceTestDetails 3",
    "count": 1,
    "visibleCount": 1
  }
}

Searching for Tags

The following example returns an array of tags that match the search term.

<Server Base URI>/api/tags/command/search?term=Test

Response:

[
  "Automated SQL UnitTests",
  "ProductPlanning Regression Tests",
  "RegressionTestDetails",
  "RegressionTests",
  "Testboard",
  "TestSetDetails",
]

Examples of the Tag API : POST

The below commands are restricted to users that have Project Admin access and will only work for projects they have scope visibility to.  A user cannot remove tags on assets they cannot see or edit in the system.

Merging Tags

The following example will merge multiple tags into a single tag.  It is possible to merge into an existing tag, or into a new tag.  This will remove all of the tags listed in the MergeFrom array in the Post Data and will add the MergeTo tag to the assets the other tags were removed from.

<Server Base URI>/api/tags/command/merge

Post Data:

{
    "MergeTo" : "Regression Tests",
    "MergeFrom" : ["RegressionTestDetails", "RegressionTests"]
}

Removing Tags

The following example will allow you to remove tags from every asset they exist on.

<Server Base URI>/api/tags/command/remove

Post Data:

{
    "removeFrom" : ["RegressionTestDetails", "RegressionTests"]
}
  • Was this article helpful?