Cloud Management API 1.5

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

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

Parameters

name required type values regexp blank? description
resource_hrefs yes Array * * no Hrefs of the resources for which tags are to be returned.

Example Responses

Click on a format below to see an example response:

JSON XML
[{
  "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

Parameters

name required type values regexp blank? description
include_tags_with_prefix no String * * no If included, all tags matching this prefix will be returned. If not included, no tags will be returned.
match_all no String true, false * no If set to 'true', resources having all the tags specified in the 'tags' parameter are returned. Otherwise, resources having any of the tags are returned.
resource_type yes String servers, instances, volumes, volume_snapshots, deployments, server_templates, multi_cloud_images, images, server_arrays, accounts, placement_groups * no Search among a single resource type.
tags yes Array * * no The tags which must be present on the resource.
with_deleted no String true, false * no If set to 'true', tags for deleted resources will also be returned. Default value is 'false'.

Example Responses

Click on a format below to see an example response:

JSON XML
[{
  "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

Parameters

name required type values regexp blank? description
resource_hrefs yes Array * * no Hrefs of the resources for which the tags are to be added.
tags yes Array * * no Tags to be added.

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

Parameters

name required type values regexp blank? description
resource_hrefs yes Array * * no Hrefs of the resources for which tags are to be deleted.
tags yes Array * * no Tags to be deleted.