feat(xo-server/rest-api): basic VM actions (#6652)

docs/restapi.md

@@ -198,6 +198,59 @@ The following query parameters are supported to customize the created VDI:
 - `name_description`
 - `raw`: this parameter must be used if importing a raw export instead of a VHD
 
+## Actions
+
+### Available actions
+
+To see the actions available on a given object, get the collection at `/rest/v0/<type>/<uuid>/actions`.
+
+For example, to list all actions on a given VM:
+
+```sh
+curl \
+  -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+  'https://xo.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/actions'
+```
+
+### Start an action
+
+Post at the action endpoint which is `/rest/v0/<type>/<uuid>/actions/<action>`.
+
+For instance, to reboot a VM:
+
+```sh
+curl \
+  -X POST \
+  -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+  'https://xo.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/actions/clean_reboot'
+```
+
+Some actions accept parameters, they should be provided in a JSON-encoded object as the request body:
+
+```sh
+curl \
+  -X POST \
+  -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json' \
+  -d '{ "name_label": "My snapshot" }' \
+  'https://xo.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/actions/snapshot'
+```
+
+By default, actions are asynchronous and return the reference of the task associated with the request.
+
+> Tasks monitoring is still under construcration and will come in a future release :)
+
+The `?sync` flag can be used to run the action synchronously without requiring task monitoring. The result of the action will be returned encoded as JSON:
+
+```console
+$ curl \
+  -X POST \
+  -b authenticationToken=KQxQdm2vMiv7jBIK0hgkmgxKzemd8wSJ7ugFGKFkTbs \
+  'https://xo.example.org/rest/v0/vms/770aa52a-fd42-8faf-f167-8c5c4a237cac/actions/clean_reboot'
+"2b0266aa-c753-6fbc-e4dd-c79be7782052"
+```
+
 ## 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>