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¶
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¶
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¶
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¶
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¶
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¶
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"
}
]
}