Xen Orchestra API
There's two different APIs to manage XCP-ng at scale via Xen Orchestra:
- a REST API, simple to use to read content
- a JSON-RPC over websocket API, more complex but coming with all features
REST API
The REST API is still is development, but the best one to read objects from a central Xen Orchestra. If you want live interactions and updates, consider using the JSON-RPC over websockets API.
Also, despite being very recent, it is versionned, so any breaking change will happen in a new URL handler. We are currently at version v0
.
Authentication
A valid authentication token should be attached as a cookie to all HTTP requests:
GET /rest/v0 HTTP/1.1
Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM
The server will respond to an invalid token with a 401 Unauthorized
status.
[Not implemented at this time] The server can request that the client updates its token with a Set-Cookie
header:
HTTP/1.1 200 OK
Set-Cookie: authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs
Usage with cURL:
curl -b \
authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
https://xo.company.lan/rest/v0/
You can use xo-cli
to create an authentication token:
$ xo-cli --createToken xoa.company.lan admin@admin.net
Password: ********
Successfully logged with admin@admin.net
Authentication token created
DiYBFavJwf9GODZqQJs23eAx9eh3KlsRhBi8RcoX0KM
Only admin users can currently use the API.
Collections request
Collections of objects are available at /<name>
(e.g. /vms
)
The following query parameters are supported:
limit
: max number of objects returnedfields
: if specified, instead of plain URLs, the results will be objects containing the requested fieldsfilter
: a string that will be used to select only matching objectsndjson
: if specified, the result will be in NDJSON format
Simple request:
GET /rest/v0/vms HTTP/1.1
Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM
HTTP/1.1 200 OK
Content-Type: application/json
[
"/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac",
"/rest/v0/vms/5019156b-f40d-bc57-835b-4a259b177be1"
]
Here is an example with curl
:
curl \
-b authenticationToken=0OQIKwb1WjeHtch25Ls \
http://xoa.example.com/rest/v0/vms?fields=name_label,power_state
[
{
"name_label": "FreeNAS",
"power_state": "Running",
"href": "/rest/v0/vms/0fc14abc-ae7a-4209-79c4-d20ca1f0e567"
},
{
"name_label": "Ubuntu 20.04 test",
"power_state": "Halted",
"href": "/rest/v0/vms/d505eb99-164e-5516-27e1-43837a01be45"
},
{
"name_label": "Rocky Linux 8",
"power_state": "Halted",
"href": "/rest/v0/vms/38f423b7-1498-ee8c-ca8d-d3bb8fcffcf2"
},
{
"name_label": "XOA 🎷",
"power_state": "Running",
"href": "/rest/v0/vms/857e34e5-c61a-f3f1-65e6-a7a9306b347b"
}
]
As NDJSON:
GET /rest/v0/vms?fields=name_label,power_state&ndjson HTTP/1.1
Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM
HTTP/1.1 200 OK
Content-Type: application/x-ndjson
{"name_label":"Debian 10 Cloudinit","power_state":"Running","url":"/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac"}
{"name_label":"Debian 10 Cloudinit self-service","power_state":"Halted","url":"/rest/v0/vms/5019156b-f40d-bc57-835b-4a259b177be1"}
VM and VDI export
VDI export and VM export are supported by the API. Below is a simple example to export a VM with zstd
compression into a myVM.xva
file:
curl \
-b authenticationToken=KQxQdm2vMiv7jFEAZXOAGKFkTbs \
'https://xoa.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237a12.xva?compress=zstd' \
> myVM.xva
For a VHD export, it's very similar:
curl \
-b authenticationToken=KQxQdm2vMiv7FkTbs \
'https://xoa.example.org/rest/v0/vdis/1a269782-ea93-4c4c-897a-475365f7b674.vhd' \
> myDisk.vhd
VDI Import
A VHD or a raw export can be imported on an SR to create a new VDI at /rest/v0/srs/<sr uuid>/vdis
.
curl \
-X POST \
-b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
-T myDisk.raw \
'https://xo.example.org/rest/v0/srs/357bd56c-71f9-4b2a-83b8-3451dec04b8f/vdis?raw&name_label=my_imported_VDI' \
| cat
Note: the final
| cat
ensures cURL's standard output is not a TTY, which is necessary for upload stats to be dislayed.
This request returns the UUID of the created VDI.
The following query parameters are supported to customize the created VDI:
name_label
name_description
raw
: this parameter must be used if importing a raw export instead of a VHD
The future
We are adding features and improving the REST API step by step. If you have interesting use cases or feedback, please ask directly at https://xcp-ng.org/forum/category/12/xen-orchestra
JSON-RPC over websockets
This is the API used between Xen Orchestra web UI and the server part, xo-server
. It's a bit harder to use than the REST API, but if you need a live subscription to events happening in your infrastructure, or to send advanced commands, this is the right one.
All features visible in your XO web UI are in fact using this API. So everything you do in the web UI is also doable in this API.
To know all the available methods you can call, the best way is to use xo-cli
to do so.
List of all commands
You can discover all available commands by running xo-cli --list-commands
with your registered XO CLI.
List all objects
xo-cli --list-objects
will print all objects you can request.