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": "4096",
"nic_model": "virtio",
"plan": "2xCPU-4GB",
"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": "4096",
"nic_model": "virtio",
"plan": "2xCPU-4GB",
"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 |