Proxmox VE API

Note: Article about Proxmox VE 2.0 beta

Introduction

Proxmox VE uses a REST like API. The concept is described in [1] (Resource Oriented Architectur - ROA).

We choose JSON as primary data format, and the whole API is formally defined using JSON Schema [2].

You can explore the API documentation at http://pve.proxmox.com/pve2-api-doc/

JSON and JSON Schema

The API use JSON as data format, because it is simple and parse-able by any web browser.

Additionally, we use JSON Schema [2] to formally describe our API. So we can automatically generate the whole API Documentation, and we can verify all parameters and return values.

An great side effect was that we are able to use JSON Schema to produce command line argument parsers automatically. In fact, the REST API and the command line tools use the same code. A small utility called 'pvesh' exposes the whole REST API on the command line.

So here is a summary of the advantage:

• easy, human readable data format (native web browser format)
• automatic parameter verification (we can also verify return values)
• automatic generation of API documentation
• easy way to create command line tools (use the same API)

API URL

The API uses the HTTPS protocol and the server listens to port 8006. So the base URL for that API is

https://your.server:8006/api2/json/

Parameters can be passed using standard HTTP techniques:

• via the URL
• using 'x-www-form-urlencoded' content-type for PUT and POST request.

It is possible specify the return format in the URL. Above example uses 'json', but you can use any of the following values:

• json: JSON
• extjs: JSON variant compatible with ExtJS forms
• html: html formated text - sometimes useful for degugging
• text: plain text - sometimes useful for degugging

Please contact use on the development mailing list if you need other data formats.

Authentification

PVE uses a Token Based Authentication. All request to the API need to include that token inside a Cookie. We usually call that token a 'ticket'. Additionally, any write request must include a CSRF prevention token inside the HTTP header. The following examples use the 'curl' command line tool.

Example: get a new ticket and the CSRF prevention token

# curl -k -d "username=root@pam&password=yourpassword"  https://10.0.0.1:8006/api2/json/access/ticket 
{ "data": { 
  "CSRFPreventionToken":"4EEC61E2:lwk7od06fa1+DcPUwBTXCcndyAY",  
  "ticket":"PVE:root@pam:4EEC61E2::rsKoApxDTLYPn6H3NNT6iP2mv...", 
  "username":"root@pam"}
}

You need to pass the returned ticket with a cookie to any further request:

curl -k -b "PVEAuthCookie=PVE:root@pam:4EEC61E2::rsKoApxDTLYPn6H3NNT6iP2mv..." https://10.0.0.1:8006/api2/json/

Additionally, any write request (POST, PUT, DELETE) must include the CSRFPreventionToken header:

curl -XDELETE -H "CSRFPreventionToken: 4EEC61E2:lwk7od06fa1+DcPUwBTXCcndyAY" ...

NOTE: Tickets have a limited lifetime of 2 hours. But you can simple get a new ticket by passing the old ticket as password to the /access/ticket method.

Using 'pvesh' to access the API

As mentioned above, there is a command line tool called 'pvesh' which exposes the whole REST API. This is the Swiss Army knife for developers and system administrators.

The tool can be run interactively, for example:

# pvesh
entering PVE shell - type 'help' for help
pve:/> ls
Dr--- access
Dr--- cluster
Dr--- nodes
Dr-c- pools
Dr-c- storage
-r--- version
pve:/> help
help [path] [--verbose]
cd [path]
ls [path]

create /pools -poolid <string> [OPTIONS]
create /storage -storage <string> -type <string> [OPTIONS]
get /version 

or you can execute single command like:

pvesh get /version

References

[1] RESTful Web Services - Web services for the real world

By Leonard Richardson and Sam Ruby, Publisher: O'Reilly Media, Released: May 2007

[2] JSON Schema links: http://json-schema.org/