1 - [Cloud Hypervisor API](#cloud-hypervisor-api)
2   - [External API](#external-api)
3     - [REST API](#rest-api)
4       - [REST API Location and availability](#rest-api-location-and-availability)
5       - [REST API Endpoints](#rest-api-endpoints)
8       - [REST API Examples](#rest-api-examples)
14     - [D-Bus API](#d-bus-api)
15       - [D-Bus API Location and availability](#d-bus-api-location-and-availability)
16       - [D-Bus API Interface](#d-bus-api-interface)
18 …- [REST API, D-Bus API and CLI Architectural Relationship](#rest-api-and-cli-architectural-relatio…
19   - [Internal API](#internal-api)
23 # Cloud Hypervisor API
25 The Cloud Hypervisor API is made of 2 distinct interfaces:
27 1. **The External API** This is the user facing API. Users and operators
29    including a REST API, a Command Line Interface (CLI) or a D-Bus based API,
32 1. **The internal API**, based on [rust's Multi-Producer, Single-Consumer (MPSC)](https://doc.rust-…
33    module. This API is used internally by the Cloud Hypervisor threads to
36 The goal of this document is to describe the Cloud Hypervisor API as a whole,
39 ## External API
41 ### REST API  argument
44 API triggers VM and VMM specific actions, and as such it is designed as a
47 The API is [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md)
48 …raw.githubusercontent.com/cloud-hypervisor/cloud-hypervisor/master/vmm/src/api/openapi/cloud-hyper…
49 for more details about the API payloads and responses.
51 #### REST API Location and availability  argument
53 The REST API, if enabled, is available as soon as the Cloud Hypervisor binary is started,
54 through either a local UNIX socket as given in the Cloud Hypervisor option `--api-socket path=...`
55 or a fd with `--api-socket fd=...`.
58 $ ./target/debug/cloud-hypervisor --api-socket path=/tmp/cloud-hypervisor.sock
60     API server: /tmp/cloud-hypervisor.sock
68 #### REST API Endpoints  argument
70 The Cloud Hypervisor API exposes the following actions through its endpoints:
76 | Check for the REST API availability | `/vmm.ping`     | N/A          | `/schemas/VmmPingResponse`…
114 enabled. Without this feature, the corresponding [REST API](#rest-api) or
115 [D-Bus API](#d-bus-api) endpoints are not available.
117 #### REST API Examples  argument
120 the REST API available at `/tmp/cloud-hypervisor.sock`:
123 $ ./target/debug/cloud-hypervisor --api-socket /tmp/cloud-hypervisor.sock
125     API server: /tmp/cloud-hypervisor.sock
149      -X PUT 'http://localhost/api/v1/vm.create'  \
168 curl --unix-socket /tmp/cloud-hypervisor.sock -i -X PUT 'http://localhost/api/v1/vm.boot'
179      -X GET 'http://localhost/api/v1/vm.info' \
190 curl --unix-socket /tmp/cloud-hypervisor.sock -i -X PUT 'http://localhost/api/v1/vm.reboot'
195 Once booted, we can shut a VM down from the REST API:
200 curl --unix-socket /tmp/cloud-hypervisor.sock -i -X PUT 'http://localhost/api/v1/vm.shutdown'
203 ### D-Bus API  argument
205 Cloud Hypervisor offers a D-Bus API as an alternative to its REST API. This
206 D-Bus API fully reflects the functionality of the REST API, exposing the
210 In addition, the D-Bus API also exposes events from `event-monitor` in the
212 see [D-Bus API Interface](#d-bus-api-interface).
214 #### D-Bus API Location and availability  argument
217 wish to use the D-Bus API, must explicitly enable it with the `dbus_api`
245 #### D-Bus API Interface  argument
247 Please refer to the [REST API](#rest-api) documentation for everything that
248 is in common with the REST API. As previously mentioned, the D-Bus API can
249 be used as a drop-in replacement for the [REST API](#rest-api).
272 Hypervisor from the CLI, you must use either the [REST API](#rest-api)
273 or the [D-Bus API](#d-bus-api).
280    to the [D-Bus API](#d-bus-api), the [REST API](#rest-api) is available
281    for controlling and managing the VM. The [D-Bus API](#d-bus-api) doesn't start
283 1. Start either the REST API, D-Bus API or both simultaneously without passing
285    booted by calling API methods of choice. It should be noted that one external
286    API does not exclude another; it is possible to have both the REST and D-Bus
289 ### REST API, D-Bus API and CLI Architectural Relationship  argument
291 The REST API, D-Bus API and the CLI all rely on a common, [internal API](#internal-api).
295 [internal API](#internal-api) commands.
297 The REST API is processed by an HTTP thread using the
300 [internal API](#internal-api) commands.
302 The D-Bus API is implemented using the [zbus](https://github.com/dbus2/zbus)
303 crate and runs in its own thread. Whenever it needs to call the [internal API](#internal-api),
306 As a summary, the REST API, the D-Bus API and the CLI are essentially frontends for the
307 [internal API](#internal-api):
311                         REST API  |                  |
318 |            |         |  D-Bus API |          |              |      | +--------------+       |
319 |    User    +---------+----------->+   zbus   +--------------+------> | Internal API |       |
333 ## Internal API
335 The Cloud Hypervisor internal API, as its name suggests, is used internally
340 and the single consumer (a.k.a. the API receiver) is the Cloud Hypervisor
343 API producers are the HTTP thread handling the [REST API](#rest-api), the
344 D-Bus thread handling the [D-Bus API](#d-bus-api) and the main thread that
349 The internal API is designed for controlling, managing and inspecting a Cloud
351 visible requests through the [REST API](#rest-api), the [D-Bus API](#d-bus-api)
354 The API follows a command-response scheme that closely maps the [REST API](#rest-api).
360 In order for the VMM control loop to respond to any internal API command, it
362 internal API command payload carry the [Sender](https://doc.rust-lang.org/std/sync/mpsc/struct.Send…
365 The sender of any internal API command is therefore responsible for:
370    end of the response channel as part of the internal API command payload.
371 1. Waiting for the internal API command's response on the [Receiver](https://doc.rust-lang.org/std/…
378 [REST API](#rest-api) call, to the reply the external user will receive:
381    [REST API](#rest-api) in order to creates a virtual machine:
387 		-X PUT 'http://localhost/api/v1/vm.create'  \
401    [MPSC](https://doc.rust-lang.org/std/sync/mpsc/) channel for the internal API
403 1. The Cloud Hypervisor HTTP thread prepares an internal API command for creating a
409 1. The Cloud Hypervisor HTTP thread sends the internal API command, and waits
421    internal API [MPSC](https://doc.rust-lang.org/std/sync/mpsc/) channel:
423    // Read from the API receiver channel
426 1. The Cloud Hypervisor control loop matches the received internal API against
446 1. The Cloud Hypervisor HTTP thread receives the internal API command response
448    control loop internal API response, it generates the appropriate HTTP