NuKVM/xen-orchestra
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore(xo-server/docs/rest-api): improve readability

Browse Source
This commit is contained in:
Julien Fontanet 2022-04-05 16:47:57 +02:00
parent 472bececb1
commit 00b740c549
1 changed files with 25 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
packages/xo-server/docs/rest-api.md
View File

@ -1,11 +1,14 @@
# REST API <!-- omit in toc -->
- [Authentication](#authentication) - [Authentication](#authentication)
- [Collections](#collections) - [Collections](#collections)
- [VM Export](#vm-export) - [VM Export](#vm-export)
- [VDI Export](#vdi-export) - [VDI Export](#vdi-export)
- [The future](#the-future)
> This [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-oriented API is experimental. Non-backward compatible changes or removal may occur in any future release. Use of the feature is not recommended in production environments. > This [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-oriented API is experimental. Non-backward compatible changes or removal may occur in any future release. Use of the feature is not recommended in production environments.
### Authentication ## Authentication
A valid authentication token should be attached as a cookie to all HTTP A valid authentication token should be attached as a cookie to all HTTP
requests: requests:
@ -17,7 +20,7 @@ Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM
The server will respond to an invalid token with a `401 Unauthorized` status. The server will respond to an invalid token with a `401 Unauthorized` status.
The server can request the client to update its token with a `Set-Cookie` header: The server can request that the client updates its token with a `Set-Cookie` header:
```http ```http
HTTP/1.1 200 OK HTTP/1.1 200 OK
@ -26,14 +29,16 @@ Set-Cookie: authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs
Usage with cURL: Usage with cURL:
``` ```bash
curl -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs https://xo.company.lan/rest/v0/ curl -b \
authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
https://xo.company.lan/rest/v0/
``` ```
You can use `xo-cli` to create an authentication token: You can use `xo-cli` to create an authentication token:
``` ```bash
> xo-cli --createToken xoa.company.lan admin@admin.net $ xo-cli --createToken xoa.company.lan admin@admin.net
Password: ******** Password: ********
Successfully logged with admin@admin.net Successfully logged with admin@admin.net
Authentication token created Authentication token created
@ -43,11 +48,11 @@ DiYBFavJwf9GODZqQJs23eAx9eh3KlsRhBi8RcoX0KM
> Only admin users can currently use the API. > Only admin users can currently use the API.
### Collections ## Collections
Collections of objects are available at `/<name>` (e.g. `/vms`) Collections of objects are available at `/<name>` (e.g. `/vms`)
Following query parameters are supported: The following query parameters are supported:
- `limit`: max number of objects returned - `limit`: max number of objects returned
- `fields`: if specified, instead of plain URLs, the results will be objects containing the requested fields - `fields`: if specified, instead of plain URLs, the results will be objects containing the requested fields
@ -56,7 +61,7 @@ Following query parameters are supported:
Simple request: Simple request:
``` ```http
GET /rest/v0/vms HTTP/1.1 GET /rest/v0/vms HTTP/1.1
Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM
@ -94,7 +99,7 @@ Content-Type: application/json
As NDJSON: As NDJSON:
``` ```http
GET /rest/v0/vms?fields=name_label,power_state&ndjson HTTP/1.1 GET /rest/v0/vms?fields=name_label,power_state&ndjson HTTP/1.1
Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM Cookie: authenticationToken=TN2YBOMYtXB_hHtf4wTzm9p5tTuqq2i15yeuhcz2xXM
@ -105,7 +110,7 @@ Content-Type: application/x-ndjson
{"name_label":"Debian 10 Cloudinit self-service","power_state":"Halted","url":"/rest/v0/vms/5019156b-f40d-bc57-835b-4a259b177be1"} {"name_label":"Debian 10 Cloudinit self-service","power_state":"Halted","url":"/rest/v0/vms/5019156b-f40d-bc57-835b-4a259b177be1"}
``` ```
### VM Export ## VM Export
A VM can be exported as an XVA at `/rest/v0/vms/<uuid>.xva`. A VM can be exported as an XVA at `/rest/v0/vms/<uuid>.xva`.
@ -114,20 +119,24 @@ By default, the XVA is not compressed, however the `compress` query parameter su
- `gzip`: use [gzip](https://en.wikipedia.org/wiki/Gzip) compression (very slow) - `gzip`: use [gzip](https://en.wikipedia.org/wiki/Gzip) compression (very slow)
- `zstd`: use [Zstandard](https://en.wikipedia.org/wiki/Zstd) compression (fast, only supported on XCP-ng) - `zstd`: use [Zstandard](https://en.wikipedia.org/wiki/Zstd) compression (fast, only supported on XCP-ng)
``` ```bash
curl \ curl \
-b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \ -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
'https://xo.company.lan/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac.xva?compress=zstd' \ 'https://xo.company.lan/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac.xva?compress=zstd' \
> export.xva > myVM.xva
``` ```
### VDI Export ## VDI Export
A VM can be exported as an VHD at `/rest/v0/vdis/<uuid>.vhd`. A VM can be exported as an VHD at `/rest/v0/vdis/<uuid>.vhd`.
``` ```bash
curl \ curl \
-b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \ -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
'https://xo.company.lan/rest/v0/vdis/1a269782-ea93-4c4c-897a-475365f7b674.vhd' \ 'https://xo.company.lan/rest/v0/vdis/1a269782-ea93-4c4c-897a-475365f7b674.vhd' \
> export.vhd > myDisk.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>