Difference between revisions of "Proxmox VE API"

From Proxmox VE
Jump to: navigation, search
(Introduction)
Line 9: Line 9:
 
==JSON and JSON Schema==
 
==JSON and JSON Schema==
  
We use JSON as data format, because it is simple and parse-able by any
+
The API use JSON as data format, because it is simple and parse-able by any
 
web browser.
 
web browser.
  
Line 18: Line 18:
 
An great side effect was that we are able to use JSON Schema to
 
An great side effect was that we are able to use JSON Schema to
 
produce command line argument parsers automatically. In fact, the REST
 
produce command line argument parsers automatically. In fact, the REST
API and the command line tools use the same code.
+
API and the command line tools use the same code. A small utility called 'pvesh'  
 
+
exposes the whole REST API on the command line.
Object linkage is done using the JSON Hyper Schema (links property).
 
 
 
A small utility called 'pvesh' exposes the whole REST API on the command
 
line.
 
  
 
So here is a summary of the advantage:
 
So here is a summary of the advantage:
Line 30: Line 26:
 
* automatic parameter verification (we can also verify return values)
 
* automatic parameter verification (we can also verify return values)
 
* automatic generation of API documentation
 
* automatic generation of API documentation
* easy way to create command line tools (us
+
* easy way to create command line tools (use the same API)
  
 
==Authentification==
 
==Authentification==

Revision as of 12:18, 17 December 2011

Yellowpin.svg 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]: 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)

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" ...

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/