https://pve.proxmox.com/mediawiki/api.php?action=feedcontributions&user=Johnnyca&feedformat=atomProxmox VE - User contributions [en]2024-03-28T22:14:25ZUser contributionsMediaWiki 1.35.11https://pve.proxmox.com/mediawiki/index.php?title=Proxmox_VE_API&diff=7375Proxmox VE API2015-07-24T19:34:18Z<p>Johnnyca: </p>
<hr />
<div>=Introduction=<br />
<br />
Proxmox VE uses a REST like API. The concept is described in [1] (Resource Oriented Architectur - ROA). <br />
<br />
We choose JSON as primary data format, and the whole API is formally defined using JSON Schema [2].<br />
<br />
You can explore the API documentation at http://pve.proxmox.com/pve2-api-doc/<br />
<br />
==JSON and JSON Schema==<br />
<br />
The API use JSON as data format, because it is simple and parse-able by any<br />
web browser.<br />
<br />
Additionally, we use JSON Schema [2] to formally describe our API. So<br />
we can automatically generate the whole API Documentation, and we can<br />
verify all parameters and return values.<br />
<br />
An great side effect was that we are able to use JSON Schema to<br />
produce command line argument parsers automatically. In fact, the REST<br />
API and the command line tools use the same code. A small utility called 'pvesh' <br />
exposes the whole REST API on the command line.<br />
<br />
So here is a summary of the advantage:<br />
<br />
* easy, human readable data format (native web browser format)<br />
* automatic parameter verification (we can also verify return values)<br />
* automatic generation of API documentation<br />
* easy way to create command line tools (use the same API)<br />
<br />
==API URL==<br />
<br />
The API uses the HTTPS protocol and the server listens to port 8006. So the base URL for that API is<br />
<br />
https://your.server:8006/api2/json/<br />
<br />
Parameters can be passed using standard HTTP techniques:<br />
<br />
* via the URL <br />
* using 'x-www-form-urlencoded' content-type for PUT and POST request.<br />
<br />
It is possible specify the return format in the URL. Above example uses 'json', but you can use any of the following values:<br />
<br />
* json: JSON <br />
* extjs: JSON variant compatible with ExtJS forms<br />
* html: html formatted text - sometimes useful for debugging<br />
* text: plain text - sometimes useful for debugging<br />
<br />
Please contact use on the development mailing list if you need other data formats.<br />
<br />
==Authentification==<br />
<br />
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.<br />
<br />
Example: get a new ticket and the CSRF prevention token<br />
<br />
<pre><br />
# curl -k -d "username=root@pam&password=yourpassword" https://10.0.0.1:8006/api2/json/access/ticket <br />
{ "data": { <br />
"CSRFPreventionToken":"4EEC61E2:lwk7od06fa1+DcPUwBTXCcndyAY", <br />
"ticket":"PVE:root@pam:4EEC61E2::rsKoApxDTLYPn6H3NNT6iP2mv...", <br />
"username":"root@pam"}<br />
}<br />
</pre><br />
<br />
<br />
You need to pass the returned ticket with a cookie to any further request:<br />
<br />
<pre><br />
curl -k -b "PVEAuthCookie=PVE:root@pam:4EEC61E2::rsKoApxDTLYPn6H3NNT6iP2mv..." https://10.0.0.1:8006/api2/json/<br />
</pre><br />
<br />
Additionally, any write request (POST, PUT, DELETE) must include the CSRFPreventionToken header:<br />
<br />
<pre><br />
curl -XDELETE -H "CSRFPreventionToken: 4EEC61E2:lwk7od06fa1+DcPUwBTXCcndyAY" ...<br />
</pre><br />
<br />
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.<br />
<br />
=Using 'pvesh' to access the API=<br />
<br />
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.<br />
<br />
The tool can be run interactively, for example:<br />
<br />
<pre><br />
# pvesh<br />
entering PVE shell - type 'help' for help<br />
pve:/> ls<br />
Dr--- access<br />
Dr--- cluster<br />
Dr--- nodes<br />
Dr-c- pools<br />
Dr-c- storage<br />
-r--- version<br />
pve:/> help<br />
help [path] [--verbose]<br />
cd [path]<br />
ls [path]<br />
<br />
create /pools -poolid <string> [OPTIONS]<br />
create /storage -storage <string> -type <string> [OPTIONS]<br />
get /version <br />
</pre><br />
<br />
or you can execute single command like:<br />
<br />
pvesh get /version<br />
pvesh get /access/users<br />
<br />
or create a new user:<br />
<br />
pvesh create /access/users -userid testuser@pve<br />
<br />
or delete that user:<br />
<br />
pvesh delete /access/users/testuser@pve<br />
<br />
or create and then launch a new container:<br />
<br />
pvesh create /nodes/{node}/openvz -vmid 100 -hostname test -storage local \<br />
-password supersecret \<br />
-ostemplate local:vztmpl/ubuntu-10.04-standard_10.04-4_i386.tar.gz \<br />
-memory 512 -swap 512 -disk 4 -cpus 1 \<br />
-ip_address 1.2.3.4<br />
pvesh create /nodes/{node}/openvz/100/status/start<br />
<br />
where ''{node}'' is the name of the node on which the container should be created.<br />
<br />
The tool automatically proxies call to other cluster members using ssh.<br />
<br />
=Clients=<br />
<br />
;PHP <br />
:https://github.com/CpuID/pve2-api-php-client<br />
:https://github.com/ZzAntares/ProxmoxVE<br />
<br />
;perl<br />
:http://search.cpan.org/~djzort/Net-Proxmox-VE-0.006/<br />
<br />
;python<br />
:https://github.com/remofritzsche/proxmox-utils<br />
:https://pypi.python.org/pypi/proxmoxer<br />
:https://pypi.python.org/pypi/pyproxmox<br />
:https://github.com/baseblack/Proxmoxia<br />
<br />
;java <br />
:https://github.com/Elbandi/pve2-api-java<br />
<br />
;ruby <br />
:https://github.com/nledez/proxmox<br />
<br />
;c#<br />
:https://github.com/ionelanton/ProxmoxSharp<br />
<br />
Please add any other clients here as they become available.<br />
<br />
=References=<br />
<br />
[1] RESTful Web Services - Web services for the real world<br />
<br />
By Leonard Richardson and Sam Ruby, Publisher: O'Reilly Media, Released: May 2007 <br />
<br />
[2] JSON Schema links: http://json-schema.org/<br />
<br />
[[Category: HOWTO]]</div>Johnnyca