Skip to content

API documentation

Jump to bottom
AeroStun edited this page Oct 15, 2019 · 23 revisions

Endpoints

The API is accessed by making HTTP requests to an endpoint URL, in which GET, POST, PUT, PATCH, and DELETE methods dictate how you interact with the available information.

The default base URL for all the HTTP endpoints is:

http://$hostname:$port/libvirt/

$hostname and $port being respectively the address and port of the Web API server

Requests

Requests must be sent over HTTP with any payload formatted in JSON. All requests must include both X-AUTH-KEY and X-AUTH-USERNAME headers to authenticate. Requests that use X-AUTH-USER-SERVICE-KEY can use that instead of the Auth-Key and Auth-Username headers.

Required headers

Name Format Description
API Key X-Auth-Key API key located in config.ini
Username X-Auth-Username Username associated with a user of group libvirt and kvm
User Service Key X-Auth-User-Service-Key Special API key good for restricted set of endpoints

Optional headers

Name Format Description
Packet ID X-Packet-ID An identifier which will be replicated in the response

Example request

Requests generally formatted as follows:

GET object/:id_type/:object_id

Auth-Username cURL (example) 

curl -X GET "http://127.0.0.1:8081/libvirt/domains/by-uuid/14" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith"

User-Service cURL (example) 

curl -X GET "http://127.0.0.1:8081/libvirt/domains/by-uuid/14" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-User-Service-Key:v1.0-e24fd090c02efcfecb4de8f4ff24..."

Responses

Format

Each response is a JSON object. The data request is wrapped in the RESULT tag. If you have a response, it will always be within the RESULT field. We also include a SUCCESS flag, an array of potential ERRORS, and MESSAGE in the response. Some responses can have additional pagination info wrapped in the RESULT_INFO

An error object will contain an integer CODE field and a MESSAGE

Date fields will always be in UTC ISO-8601 format, including microseconds.

JSon type response

{
  "results": Array of $result,
  "success": boolean,
  "errors": Array of $error,
  "messages": Array of strings
}

$result is an object specific to each request.

$error is an object determined with a CODE (integer) and a MESSAGE (string) :

{
  "code": integer,
  "message": string
}

For a list of errors, see Errors.

Success Response (example) 

{
  "results": [
    {
      "uuid": "4dea22b3-1d52-d8f3-2516-782e98ab3fa0",
      "name": "debian-vm",
      "...": "..."
    },
    {
      "uuid": "fa8e1003-1f3f-4a92-a829-66dd523a68f5",
      "name": "manjaro",
      "...": "..."
    }
  ],
  "success": true,
  "errors": [],
  "messages": []
}

Error Response (example) 

{
  "results": [],
  "success": false,
  "errors": [
    {
      "code": 42,
      "message": "Invalid or missing domain."
    }
  ],
  "messages": []
}

Domains

A Domain is a virtual machine on a host. It can be characterized by a name (max 253 characters string) or an UUID (string of 32 characters separated by - : XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX)

List Domains

List, search, sort, and filter your domains

GET domains:flags

Optional parameters

Name type Description example Constraints
state number or string Domain state Running See Status flags
active boolean Activity specifier true or false
persistent boolean Persistence specifier true or false
managed_save boolean Save management policy specifier true or false
has_snapshot boolean Snaphshot policy specifier true or false

N.B. : Flags can be composed with a comma , e.g., ?flag=val1,val2

cURL (example) 

curl -X GET "http://127.0.0.1:8081/libvirt/domains?state=running&has_snapshot=true" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith"

Create Domain

with user-provided XML

curl -X POST "http://127.0.0.1:8081/libvirt/domains" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith" \
     --data '"<domain>...</domain>"'

with auto-generated XML (not implemented)

cURL (example) 

curl -X POST "http://127.0.0.1:8081/libvirt/domains" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith" \
     --data '{"name":"fedora-vm","os":"Linux"}'

You may also send in an array of domains to be created

Domains Details

GET domains/:identifier_type/:identifier

:identifier_type can be by-name or by-uuid

cURL (example) 

curl -X GET "http://127.0.0.1:8081/libvirt/domains/by-uuid/4dea22b3-1d52-d8f3-2516-782e98ab3fa0" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith"

Domains XML description

GET domains/:identifier_type/:identifier/xml_desc

Return the XML description of :identifier as a string.

cURL (example) 

curl -X GET "http://127.0.0.1:8081/libvirt/domains/by-uuid/4dea22b3-1d52-d8f3-2516-782e98ab3fa0/xml_desc" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith"

JSon return example

{
  "results": [
    "<domain>...</domain>"
  ],
  "success": true,
  "errors": [],
  "messages": []
}

Manage domains

PATCH domains/:identifier_type/:identifier

Power management (JSON grammar)

The JSon data can be an obect or an array of objects if you need to compose multiple requests relating to this domain.

{
  "power_mgt": "$VALUE"
}

$VALUE can be a string (see $ACTION values) or a JSON Object :

{
  "$VALUE": {
    "request": "$ACTION",
    "type": "$FLAGS"
  }
}

For flags, see Power management flags.

If no flags are specified, using no flag.

$ACTION values (according to virsh)

Value (string) Action
start Start a (previously defined) inactive domain
shutdown Gracefully shutdown a domain
destroy Destroy (stop) a domain
reboot Reboot a domain
reset Reset a domain
suspend Suspend (pause) a domain
resume Resume (unpause)

cURL (example: start) 

curl -X PATCH "http://127.0.0.1:8081/libvirt/domains/by-name/debian-vm" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith" \
     --data '[{"power_mgt":{"request":"start", "type":"ACPI_POWER_BTN"}}]'

N.B. : In this example, the array is useless, it serves only for example purposes.

Success response (example) 

{
  "results": [],
  "success": true,
  "errors": [],
  "messages": [
    {
      "start": "Domain started"
    }
  ]
}

Error response (example) 

{
  "results": [],
  "success": false,
  "errors": [
    {
      "code": 201,
      "message": "Domain is already active"
    }
  ],
  "messages": []
}

Delete domains

DELETE domains/:identifier_type/:identifier:options

The request can contain embedded args to specify options. See Delete flags. These options may be required, e.g., if your domain has NVRAM, you have to specify if you want to keep the NVRAM file or delete it.

cURL (example) 

curl -X PATCH "http://127.0.0.1:8081/libvirt/domains/by-name/debian-vm?options=keep_nvram" \
     -H "Content-Type:application/json" \
     -H "X-Auth-Key:1234567893feefc5f0q5000bfo0c38d90bbeb" \
     -H "X-Auth-Username:smith"
Clone this wiki locally