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