[pve-devel] Proxmox Backup API

[Thomas Lamprecht]

Hi Dennis,

Am 08.07.25 um 05:07 schrieb Dennis Klochko:
> Thank you for the extra information, that's very helpful.
> Another question is about versioning of a plugin vs new Proxmox versions -
> in what cases should the plugin be updated?

We had a short section about [api versioning] in the storage plugin
development wiki article already, I extended it slightly to provide
some more information.

[api versioning]: https://pve.proxmox.com/wiki/Storage_Plugin_Development#API_Versioning

In general, we do not try to make hard breaks if anyhow avoidable.
That means that we normally bump the API age alongside the API version,
especially for updates during a stable release series.
On new major releases, which are due roughly every two years, we might
reduce some technical debt and make bigger changes, but even there we
try hard to not fully reset the API age to zero, but rather try to still
support the last previous major version to make updates easier for our
users and also third-party integrations.

There is a link to an [example] for how one can handle returning the
API version inside a plugin such that it can be used for a broad range
of versions, and we got an [API changelog] file tracking historic API
changes in the pve-storage git repository, if you want to see what such
bumps can entail in practice.

[example]: https://git.proxmox.com/?p=pve-storage-plugin-examples.git;a=blob;f=backup-provider-directory/src/PVE/Storage/Custom/BackupProviderDirExamplePlugin.pm;h=57df944c0475d914e2171c5b29744376eb057a5c;hb=HEAD#l37

[API changelog]: https://git.proxmox.com/?p=pve-storage.git;a=blob;f=ApiChangeLog

- Thomas