Tags

A tag or machine tag is a useful way of attaching useful metadata to an object/resource. Tags are commonly used as an extra label or identifier. For example, you might want to add a tag to an EBS Snapshot or AMI so that you can find it more quickly.

Actions

• by_resource
• by_tag
• multi_add
• multi_delete

by_resource

Get tags for a list of resource hrefs. The hrefs can belong to various resource types and the tags for a non-existent href will be empty.

URLs

POST /api/tags/by_resource

HTTP response code

200 OK

Content-type

application/vnd.rightscale.resource_tag;type=collection

Required roles

• observer||instance||infrastructure

Parameters

Example Responses

[{
  "tags": [
    {
      "name": "color:red=false"
    },
    {
      "name": "color:blue=true"
    }
  ],
  "links": [
    {"rel":"resource","href":"/api/servers/10"},
    {"rel":"resource","href":"/api/clouds/1/volumes/ABC"}
  ],
  "actions": [

  ]
},{
  "tags": [
    {
      "name": "color:red=true"
    },
    {
      "name": "color:blue=false"
    }
  ],
  "links": [
    {"rel":"resource","href":"/api/servers/20"}
  ],
  "actions": [

  ]
}]

<?xml version="1.0" encoding="UTF-8"?>
<resource_tags>
  <resource_tag>
    <tags>
      <tag>
        <name>color:red=false</name>
      </tag>
      <tag>
        <name>color:blue=true</name>
      </tag>
    </tags>
    <links>
      <link rel="resource" href="/api/servers/10"/>
      <link rel="resource" href="/api/clouds/1/volumes/ABC"/>
    </links>
    <actions/>
  </resource_tag>
  <resource_tag>
    <tags>
      <tag>
        <name>color:red=true</name>
      </tag>
      <tag>
        <name>color:blue=false</name>
      </tag>
    </tags>
    <links>
      <link rel="resource" href="/api/servers/20"/>
    </links>
    <actions/>
  </resource_tag>
</resource_tags>

by_tag

Search for resources having a list of tags in a specific resource_type.

The search criteria can contain plain tags ("my_db_server"), machine tags ("server:db=true"), or namespace & predicate wildcards ("server:db=*"). The result set includes links to the resources.

If match_all is "true", then the search is an "AND" operation -- only resources having all the tags are returned. If match_all has any other value or is missing, the search is performed as an "OR" operation.

PLEASE NOTE the behavior of the include_tags_with_prefix parameter: if it is absent, or blank, then you will find resources that match your query but receive no information about the tags that apply to those resources. (Your search will also complete much more quickly in this case.)

For example, a search with tag[]="server:db=true" and include_tags_with_prefix="backup:" will return resources that are tagged as a DB server, and also return all "backup" related tags for every matching resource.

URLs

POST /api/tags/by_tag

HTTP response code

200 OK

Content-type

application/vnd.rightscale.resource_tag;type=collection

Required roles

• observer||instance||infrastructure

Parameters

Example Responses

[{
  "tags": [
    {
      "name": "color:red=false"
    },
    {
      "name": "color:blue=true"
    }
  ],
  "links": [
    {"rel":"resource","href":"/api/servers/10"},
    {"rel":"resource","href":"/api/clouds/1/volumes/ABC"}
  ],
  "actions": [

  ]
},{
  "tags": [
    {
      "name": "color:red=true"
    },
    {
      "name": "color:blue=false"
    }
  ],
  "links": [
    {"rel":"resource","href":"/api/servers/20"}
  ],
  "actions": [

  ]
}]

<?xml version="1.0" encoding="UTF-8"?>
<resource_tags>
  <resource_tag>
    <tags>
      <tag>
        <name>color:red=false</name>
      </tag>
      <tag>
        <name>color:blue=true</name>
      </tag>
    </tags>
    <links>
      <link rel="resource" href="/api/servers/10"/>
      <link rel="resource" href="/api/clouds/1/volumes/ABC"/>
    </links>
    <actions/>
  </resource_tag>
  <resource_tag>
    <tags>
      <tag>
        <name>color:red=true</name>
      </tag>
      <tag>
        <name>color:blue=false</name>
      </tag>
    </tags>
    <links>
      <link rel="resource" href="/api/servers/20"/>
    </links>
    <actions/>
  </resource_tag>
</resource_tags>

multi_add

Add a list of tags to a list of hrefs. The tags must be either plain_tags or machine_tags. The hrefs can belong to various resource types. If a resource for a href could not be found, an error is returned and no tags are added for any resource.

No error will be raised if the resource already has the tag(s) you are trying to add.

Note: At this point, tags on 'next_instance' are not supported and one has to add tags to the 'server'.

URLs

POST /api/tags/multi_add

HTTP response code

204 No Content

Required roles

• actor||instance

Parameters

multi_delete

Delete a list of tags on a list of hrefs. The tags must be either plain_tags or machine_tags. The hrefs can belong to various resource types. If a resource for a href could not be found, an error is returned and no tags are deleted for any resource.

Note that no error will be raised if the resource does not have the tag(s) you are trying to delete.

URLs

POST /api/tags/multi_delete

HTTP response code

204 No Content

Required roles

• actor||instance

Parameters