Tags

Allowed HTTP methods

Method Description
GET get / list object/s
POST create new object/s
PUT update / modify object/s
DELETE delete object/s

Note

See RFC 2616#section-9 for more details on HTTP methods semantics

Listing

GET /tags/

Gets the list of tags to which the authenticated user has access.

statuscode 200:no error

Example request:

GET /api/2.0/tags/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": "MyGroupOfThings",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/",
            "resources": [],
            "uuid": "7b102579-e850-47cf-adf9-9c1a499b08f8"
        },
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
                    "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
                    "uuid": "f52db291-f754-4434-acac-77268cbac94f"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            ],
            "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
        }
    ]
}

List single tag

GET /tag/(uuid: tag_uuid)/

Gets detailed information for tag identified by tag_uuid.

statuscode 200:no error

Example request:

GET /api/2.0/tags/c66a2113-be9b-4157-93ac-fb8c0e82087c/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {},
    "name": "TagCreatedWithResource",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "vlans",
            "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
            "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
            "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
            "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
            "uuid": "f52db291-f754-4434-acac-77268cbac94f"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "ips",
            "resource_uri": "/api/2.0/ips/185.12.6.183/",
            "uuid": "185.12.6.183"
        }
    ],
    "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
}

Creating

POST /tags/

Creates a new tag or multiple tags.

statuscode 201:object created

Example request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "MyGroupOfThings"
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "MyGroupOfThings",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/",
            "resources": [],
            "uuid": "7b102579-e850-47cf-adf9-9c1a499b08f8"
        }
    ]
}

It is possible to add resources to a tag at creation time. Just specify their UUIDs the resources list:

Example request:

POST /api/2.0/tags/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "TagCreatedWithResource",
            "resources": [
                "401d5ba4-6544-47ef-bf61-54bafe59d871",
                "3576136a-0a7e-4ece-8050-f2e408fbca96",
                "9214aa22-10db-4aff-92f2-779a043b13c7",
                "94.26.101.182",
                "10619300-edda-42ba-91e0-7e3df0689d00"
            ]
        }
    ]
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/96537817-f4b6-496b-a861-e74192d3ccb0/",
                    "uuid": "96537817-f4b6-496b-a861-e74192d3ccb0"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
                    "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                    "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/f52db291-f754-4434-acac-77268cbac94f/",
                    "uuid": "f52db291-f754-4434-acac-77268cbac94f"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/185.12.6.183/",
                    "uuid": "185.12.6.183"
                }
            ],
            "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
        }
    ]
}

Editing

PUT /tags/{uuid}/

Edits a tag. It is possible to add or remove resources to a tag by replacing the resources list with a new one:

statuscode 200:no error

Example request:

PUT /api/2.0/tags/c66a2113-be9b-4157-93ac-fb8c0e82087c/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "TagCreatedWithResource",
    "resources": [
        "a15d7e36-a392-4328-9cb1-616c9107eb26",
        "9214aa22-10db-4aff-92f2-779a043b13c7"
    ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {},
    "name": "TagCreatedWithResource",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/tags/c91f7742-e3b9-4794-a178-f0831ee1d3d2/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd/",
            "uuid": "08b9874a-4b2c-4c33-a06e-bed5e0bfa6fd"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "res_type": "snapshots",
            "resource_uri": "/api/2.0/snapshots/00fc1dd8-893b-4b51-b859-8d5f1ef0cf7f/",
            "uuid": "00fc1dd8-893b-4b51-b859-8d5f1ef0cf7f"
        }
    ],
    "uuid": "c91f7742-e3b9-4794-a178-f0831ee1d3d2"
}

It is also possible to edit the tags on the resource itself by replacing the tags list. For example here is how to add a tag from a server:

Example request:

PUT /api/2.0/servers/3576136a-0a7e-4ece-8050-f2e408fbca96/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3576136a-0a7e-4ece-8050-f2e408fbca96/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        "00f4ea87-891c-4ee9-a28f-21e25b96dd48",
        "c66a2113-be9b-4157-93ac-fb8c0e82087c"
    ],
    "uuid": "3576136a-0a7e-4ece-8050-f2e408fbca96",
    "vnc_password": "pass"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpu_type": "amd",
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "grantees": [],
    "hv_relaxed": false,
    "hv_tsc": false,
    "hypervisor": "kvm",
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/c2fc9982-cf2e-434a-bf63-e22a27b39f00/",
        "uuid": "c2fc9982-cf2e-434a-bf63-e22a27b39f00"
    },
    "permissions": [],
    "pubkeys": [],
    "requirements": [],
    "resource_uri": "/api/2.0/servers/3576136a-0a7e-4ece-8050-f2e408fbca96/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/00f4ea87-891c-4ee9-a28f-21e25b96dd48/",
            "uuid": "00f4ea87-891c-4ee9-a28f-21e25b96dd48"
        },
        {
            "resource_uri": "/api/2.0/tags/c66a2113-be9b-4157-93ac-fb8c0e82087c/",
            "uuid": "c66a2113-be9b-4157-93ac-fb8c0e82087c"
        }
    ],
    "uuid": "3576136a-0a7e-4ece-8050-f2e408fbca96",
    "vnc_password": "pass"
}

Deleting

DELETE /tags/{uuid}/

Deletes a single tag.

statuscode 204:No content, object deletion started.

Example request:

DELETE /api/2.0/tags/00f4ea87-891c-4ee9-a28f-21e25b96dd48/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Filter Servers, Drives, IPs or VLANs listing by tag

GET /tags/{uuid}/{resource_type}/

Lists the objects of the given resource_type which is one of ‘servers’, ‘drives’, ‘ips’, ‘vlans’.

statuscode 200:no error

Example request:

GET /api/2.0/tags/7b102579-e850-47cf-adf9-9c1a499b08f8/servers/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "name": "test_server2",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": {
                "resource_uri": "/api/2.0/servers/cdeca2cf-4628-4169-8a3a-ceebedd9ea3a/",
                "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
            },
            "runtime": null,
            "status": "stopped",
            "uuid": "cdeca2cf-4628-4169-8a3a-ceebedd9ea3a"
        }
    ]
}