TAGS

User can define a set of free-form tags to group and identify a subset of their servers. Tags can be for example webserver, database, PROD, QA, DEV etc.

A server can have several tags. API can be used to return only servers matching specified tags. Note that all operations changing server's state or attributes must still be done individually for each server UUID, tags can be used only to return a list of servers.

Creating and modifying tags is allowed only by main account. Sub-accounts have access only to listing tags and tagging servers they are granted access to.

List existing tags

Returns all existing tags with their properties and servers tagged.

Request

GET /1.2/tag

Normal response

HTTP/1.0 200 OK
{
  "tags": {
    "tag": [
      {
        "description": "Development servers",
        "name": "DEV",
        "servers": {
          "server": [
            "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
          ]
        }
      },
      {
        "description": "My own servers",
        "name": "private",
        "servers": {
          "server": []
        }
      },
      {
        "description": "Production servers",
        "name": "PROD",
        "servers": {
          "server": []
        }
      }
    ]
  }
}

Create a new tag

Creates a new tag. Existing servers can be tagged in same request.

Request

POST /1.2/tag
{
  "tag": {
    "name": "DEV",
    "description": "Development servers",
    "servers": { 
      "server": [
        "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
      ]
    }
  }
}

Normal response

HTTP/1.0 200 OK
{
  "tag": {
    "name": "DEV",
    "description": "Development servers",
    "servers": { 
      "server": [
        "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
      ]
    }
  }
}

Attributes

Attributes Accepted values Default value Required Description
name 1-32 characters A-Z, a-z, 0-9, _ Yes The new tag
description A string of max 255 characters No Description of the tag
servers A server element with a list of server UUIDs No List of valid UUIDs of existing servers to be tagged

Error responses

HTTP status Error code Description
400 TAG_INVALID The tag name is invalid
403 TAG_FORBIDDEN Username does not have access to this tag
409 TAG_EXISTS Tag already exists

Modify existing tag

Changes attributes of an existing tag

Request

PUT /1.2/tag/DEV
{
  "tag": {
    "name": "PROD",
    "description": "Production servers",
    "servers": { 
      "server": [
        "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
      ]
    }
  }
}

Normal response

HTTP/1.0 200 OK
{
  "tag": {
    "name": "PROD",
    "description": "Production servers",
    "servers": { 
      "server": [
        "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
      ]
    }
  }
}

Error responses

HTTP status Error code Description
400 TAG_INVALID The tag name is invalid
403 TAG_FORBIDDEN Username does not have access to this tag
404 TAG_NOT_FOUND Tag does not exist
409 TAG_EXISTS Tag already exists

Attributes are same as with new tag creation

Delete tag

Deleting existing tag untags all servers from specified tag and deletes tag definition.

Request

DELETE /1.2/tag/TEST

Normal response

HTTP/1.0 204 OK

Error responses

HTTP status Error code Description
400 TAG_INVALID The tag name is invalid
403 TAG_FORBIDDEN Username does not have access to this tag
404 TAG_NOT_FOUND Tag does not exist

Assign tag to a server

Servers can be tagged with one or more tags. The tags used must exist.

Request

POST /1.2/server/00c78863-db86-44ea-af70-d6edc4d162b/tag/DEV,private,RHEL

Normal response

HTTP/1.0 200 OK
{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "ip_addresses": {
      "ip_address": [
        {
          "access": "private",
          "address": "10.0.0.0",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "x.x.x.x",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
          "family": "IPv6"
        }
      ]
    },
    "license": 0,
    "memory_amount": "2048",
    "nic_model": "virtio",
    "plan": "2xCPU-2GB",
    "plan_ipv4_bytes": "345346754423",
    "plan_ipv6_bytes": "676300234",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "part_of_plan": "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": 50,
          "storage_title": "Debian from a template",
          "type": "disk"
        }
      ]
    },
    "tags": {
       "tag": [
          "DEV",
          "private",
          "RHEL"
       ]
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "vnc": "off",
    "vnc_password": "aabbccdd",
    "zone": "fi-hel1"
  }
}

Error responses

HTTP status Error code Description
400 TAG_INVALID The tag name is invalid
403 TAG_FORBIDDEN Username does not have access to this tag
404 TAG_NOT_FOUND Tag does not exist

Remove tag from server

Untags tags from given server. The tag(s) must exist.

Request

POST /1.2/server/00c78863-db86-44ea-af70-d6edc4d162b/untag/private

Normal response

HTTP/1.0 200 OK
{
  "server": {
    "boot_order": "disk",
    "core_number": "2",
    "firewall": "on",
    "hostname": "debian.example.com",
    "ip_addresses": {
      "ip_address": [
        {
          "access": "private",
          "address": "10.0.0.0",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "x.x.x.x",
          "family": "IPv4"
        },
        {
          "access": "public",
          "address": "xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx",
          "family": "IPv6"
        }
      ]
    },
    "license": 0,
    "memory_amount": "2048",
    "nic_model": "virtio",
    "plan": "2xCPU-2GB",
    "plan_ipv4_bytes": "345346754423",
    "plan_ipv6_bytes": "676300234",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "part_of_plan": "yes",
          "storage": "0169b4f8-051c-4a86-9484-f5b798249949",
          "storage_size": 50,
          "storage_title": "Debian from a template",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "RHEL"
      ]
    },
    "timezone": "UTC",
    "title": "My Debian server",
    "uuid": "00c78863-db86-44ea-af70-d6edc4d162bf",
    "video_model": "cirrus",
    "vnc": "off",
    "vnc_password": "aabbccdd",
    "zone": "fi-hel1"
  }
}

Error responses

HTTP status Error code Description
400 TAG_INVALID The tag name is invalid
403 TAG_FORBIDDEN Username does not have access to this tag
404 TAG_NOT_FOUND Tag does not exist