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 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/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/tags/6f0328c0-92a1-4a77-ba64-7e8951d495fa/",
            "resources": [],
            "uuid": "6f0328c0-92a1-4a77-ba64-7e8951d495fa"
        },
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/tags/21014c24-8470-4065-931c-169276fbb9e1/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/162.213.37.151/",
                    "uuid": "162.213.37.151"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/4e7702c4-882e-427b-aaba-cb5accd98b6e/",
                    "uuid": "4e7702c4-882e-427b-aaba-cb5accd98b6e"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/590cab8f-aeca-4dd6-8ea8-12aee1e8cac1/",
                    "uuid": "590cab8f-aeca-4dd6-8ea8-12aee1e8cac1"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/a21a4e59-b133-487a-ad7b-16b41ac38e9b/",
                    "uuid": "a21a4e59-b133-487a-ad7b-16b41ac38e9b"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/c3c49c01-47e0-45cb-b89e-106427e49706/",
                    "uuid": "c3c49c01-47e0-45cb-b89e-106427e49706"
                }
            ],
            "uuid": "21014c24-8470-4065-931c-169276fbb9e1"
        }
    ]
}

Detailed listing

GET /tags/detail/

Gets the detailed list of tags with additional information to which the authenticated user has access, like the tagged resource

statuscode 200:no error

Example request:

GET /api/2.0/tags/detail/?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/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
                "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
            },
            "resource_uri": "/api/2.0/tags/0f8a7d5b-1775-40d2-8bf8-293f52bdf964/",
            "resources": [],
            "uuid": "0f8a7d5b-1775-40d2-8bf8-293f52bdf964"
        },
        {
            "meta": {},
            "name": "TagCreatedWithResource",
            "owner": {
                "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
                "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
            },
            "resource_uri": "/api/2.0/tags/ff850ca3-f300-4c00-b19f-07739bbf5830/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
                        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/2aee4b06-0d40-47d6-b9d7-028f659f8234/",
                    "uuid": "2aee4b06-0d40-47d6-b9d7-028f659f8234"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
                        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/fda95788-5fee-4555-8561-b69b943fca69/",
                    "uuid": "fda95788-5fee-4555-8561-b69b943fca69"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
                        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/31.171.248.53/",
                    "uuid": "31.171.248.53"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
                        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/4f430b7a-0fa6-4a9f-81e9-7a976ec9f835/",
                    "uuid": "4f430b7a-0fa6-4a9f-81e9-7a976ec9f835"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/42cb107b-d57a-4808-93d9-2d3f9ae4fe71/",
                        "uuid": "42cb107b-d57a-4808-93d9-2d3f9ae4fe71"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/053cffa0-ead3-403a-a432-cc8758523ea4/",
                    "uuid": "053cffa0-ead3-403a-a432-cc8758523ea4"
                }
            ],
            "uuid": "ff850ca3-f300-4c00-b19f-07739bbf5830"
        }
    ]
}

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/21014c24-8470-4065-931c-169276fbb9e1/ 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/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
    },
    "resource_uri": "/api/2.0/tags/21014c24-8470-4065-931c-169276fbb9e1/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "res_type": "ips",
            "resource_uri": "/api/2.0/ips/162.213.37.151/",
            "uuid": "162.213.37.151"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/4e7702c4-882e-427b-aaba-cb5accd98b6e/",
            "uuid": "4e7702c4-882e-427b-aaba-cb5accd98b6e"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/590cab8f-aeca-4dd6-8ea8-12aee1e8cac1/",
            "uuid": "590cab8f-aeca-4dd6-8ea8-12aee1e8cac1"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "res_type": "vlans",
            "resource_uri": "/api/2.0/vlans/a21a4e59-b133-487a-ad7b-16b41ac38e9b/",
            "uuid": "a21a4e59-b133-487a-ad7b-16b41ac38e9b"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "res_type": "servers",
            "resource_uri": "/api/2.0/servers/c3c49c01-47e0-45cb-b89e-106427e49706/",
            "uuid": "c3c49c01-47e0-45cb-b89e-106427e49706"
        }
    ],
    "uuid": "21014c24-8470-4065-931c-169276fbb9e1"
}

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/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/tags/6f0328c0-92a1-4a77-ba64-7e8951d495fa/",
            "resources": [],
            "uuid": "6f0328c0-92a1-4a77-ba64-7e8951d495fa"
        }
    ]
}

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": [
                "4e7702c4-882e-427b-aaba-cb5accd98b6e",
                "c3c49c01-47e0-45cb-b89e-106427e49706",
                "590cab8f-aeca-4dd6-8ea8-12aee1e8cac1",
                "162.213.37.151",
                "a21a4e59-b133-487a-ad7b-16b41ac38e9b"
            ]
        }
    ]
}

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/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": "/api/2.0/tags/21014c24-8470-4065-931c-169276fbb9e1/",
            "resources": [
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "ips",
                    "resource_uri": "/api/2.0/ips/162.213.37.151/",
                    "uuid": "162.213.37.151"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/4e7702c4-882e-427b-aaba-cb5accd98b6e/",
                    "uuid": "4e7702c4-882e-427b-aaba-cb5accd98b6e"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "drives",
                    "resource_uri": "/api/2.0/drives/590cab8f-aeca-4dd6-8ea8-12aee1e8cac1/",
                    "uuid": "590cab8f-aeca-4dd6-8ea8-12aee1e8cac1"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "vlans",
                    "resource_uri": "/api/2.0/vlans/a21a4e59-b133-487a-ad7b-16b41ac38e9b/",
                    "uuid": "a21a4e59-b133-487a-ad7b-16b41ac38e9b"
                },
                {
                    "owner": {
                        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
                    },
                    "res_type": "servers",
                    "resource_uri": "/api/2.0/servers/c3c49c01-47e0-45cb-b89e-106427e49706/",
                    "uuid": "c3c49c01-47e0-45cb-b89e-106427e49706"
                }
            ],
            "uuid": "21014c24-8470-4065-931c-169276fbb9e1"
        }
    ]
}

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/21014c24-8470-4065-931c-169276fbb9e1/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "name": "TagCreatedWithResource",
    "resources": [
        "d707877a-884d-450e-a788-2062f8973e5e",
        "590cab8f-aeca-4dd6-8ea8-12aee1e8cac1"
    ]
}

Example response:

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

{
    "meta": {},
    "name": "TagCreatedWithResource",
    "owner": {
        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
    },
    "resource_uri": "/api/2.0/tags/21014c24-8470-4065-931c-169276fbb9e1/",
    "resources": [
        {
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "res_type": "snapshots",
            "resource_uri": "/api/2.0/snapshots/d707877a-884d-450e-a788-2062f8973e5e/",
            "uuid": "d707877a-884d-450e-a788-2062f8973e5e"
        },
        {
            "owner": {
                "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "res_type": "drives",
            "resource_uri": "/api/2.0/drives/590cab8f-aeca-4dd6-8ea8-12aee1e8cac1/",
            "uuid": "590cab8f-aeca-4dd6-8ea8-12aee1e8cac1"
        }
    ],
    "uuid": "21014c24-8470-4065-931c-169276fbb9e1"
}

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/c3c49c01-47e0-45cb-b89e-106427e49706/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
    },
    "requirements": [],
    "resource_uri": "/api/2.0/servers/c3c49c01-47e0-45cb-b89e-106427e49706/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        "6f0328c0-92a1-4a77-ba64-7e8951d495fa",
        "21014c24-8470-4065-931c-169276fbb9e1"
    ],
    "uuid": "c3c49c01-47e0-45cb-b89e-106427e49706",
    "vnc_password": "pass"
}

Example response:

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

{
    "context": true,
    "cpu": 1000,
    "cpu_model": null,
    "cpus_instead_of_cores": false,
    "drives": [],
    "enable_numa": false,
    "hv_relaxed": false,
    "hv_tsc": false,
    "jobs": [],
    "mem": 536870912,
    "meta": {},
    "name": "test_server2",
    "nics": [],
    "owner": {
        "resource_uri": "/api/2.0/user/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
        "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
    },
    "requirements": [],
    "resource_uri": "/api/2.0/servers/c3c49c01-47e0-45cb-b89e-106427e49706/",
    "runtime": null,
    "smp": 1,
    "status": "stopped",
    "tags": [
        {
            "resource_uri": "/api/2.0/tags/6f0328c0-92a1-4a77-ba64-7e8951d495fa/",
            "uuid": "6f0328c0-92a1-4a77-ba64-7e8951d495fa"
        },
        {
            "resource_uri": "/api/2.0/tags/21014c24-8470-4065-931c-169276fbb9e1/",
            "uuid": "21014c24-8470-4065-931c-169276fbb9e1"
        }
    ],
    "uuid": "c3c49c01-47e0-45cb-b89e-106427e49706",
    "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/6f0328c0-92a1-4a77-ba64-7e8951d495fa/ 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/6f0328c0-92a1-4a77-ba64-7e8951d495fa/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/80cb30fb-0ea3-43db-b27b-a125752cc0bf/",
                "uuid": "80cb30fb-0ea3-43db-b27b-a125752cc0bf"
            },
            "resource_uri": {
                "resource_uri": "/api/2.0/servers/c3c49c01-47e0-45cb-b89e-106427e49706/",
                "uuid": "c3c49c01-47e0-45cb-b89e-106427e49706"
            },
            "runtime": null,
            "status": "stopped",
            "uuid": "c3c49c01-47e0-45cb-b89e-106427e49706"
        }
    ]
}