The Proxmox VE API from Java

By developers, for developers.

Built by Corsinvest, official Proxmox partner.

Maven

<!-- pom.xml: the latest version is on Maven Central -->
<dependency>
    <groupId>it.corsinvest.proxmoxve</groupId>
    <artifactId>cv4pve-api-java</artifactId>
    <version>9.2.3</version>
</dependency>

Gradle

// build.gradle: the latest version is on Maven Central
implementation 'it.corsinvest.proxmoxve:cv4pve-api-java:9.2.3'

Why

An application that manages Proxmox VE (a customer portal, a scheduled job, a monitoring or billing tool) has to speak its REST API: tickets and tokens, paths, parameters, JSON, tasks that end later. Written by hand it is a layer of HTTP code to build and to keep up with every Proxmox VE release.

cv4pve-api-java is that layer, generated from the API itself. The calls follow the tree of the API, so the Proxmox VE API viewer is also the reference of the client, and the Javadoc of each method carries the same descriptions.

import it.corsinvest.proxmoxve.api.PveClient;

var client = new PveClient("pve01", 8006);
client.setApiToken("automation@pve!app=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee");

// GET /nodes/{node}/qemu/{vmid}/status/current
var result = client.getNodes().get("pve01").getQemu().get(100).getStatus().getCurrent().vmStatus();

System.out.println(result.isSuccessStatusCode()
        ? "VM " + result.getData().get("vmid").asInt() + " is " + result.getData().get("status").asText()
        : result.getStatusCode() + " " + result.getReasonPhrase());

From endpoint to methodPaths become getters and get(...), the methods of an endpoint become Java methods, parameters become arguments.

In your application, API only

The client runs where Java 17 or later runs (Windows, Linux, macOS, a container, a CI runner) and talks only to the Proxmox VE REST API on port 8006. Nothing is installed on the nodes and no SSH is needed. What an application can do is what its API token or user is allowed to do: give it a token with just the privileges it needs, see Permissions.

Where it fits

The cv4pve suite follows the Unix philosophy: each tool does one thing and does it well. This library is the Java way into the same API the tools of the suite use. If a ready tool already does the job, use the tool: cv4pve-cli calls the API from any shell, cv4pve-autosnap takes snapshots with retention. The same client exists for .NET with cv4pve-api-dotnet and for PowerShell with cv4pve-api-powershell.

What it does for you

The whole API

A method for every endpoint and HTTP method, generated from the Proxmox VE API schema, placed where the API has it: the path of an endpoint is the path in the code.

One Result for every call

The HTTP outcome and the Proxmox VE data together, read as a Jackson JsonNode. A failed call does not throw.

API token or password

Connect with an API token or a user and password, with two-factor authentication, certificate validation, timeout and proxy.

Tasks

Start a backup, a clone or a migration, wait for its task to finish and read whether it succeeded.

Raw calls

GET, POST, PUT and DELETE on any path with a map of parameters: for the calls with many options and for endpoints newer than the library.

One dependency

Java 17 or later and Jackson. No framework, no HTTP library to configure.

Part of the cv4pve suite →

Write your first call

Add the dependency from Maven Central, connect to any node, read your VMs.

Made by Corsinvest,
official Proxmox partner

Get startedProfessional support