# API Versioning ChangeLog

Our API versioning contains an `APIVER` and an `APIAGE`.
The `APIAGE` is the number of versions we're backward compatible with. (iow.  things got added
without breaking anything unaware of it.)

Future changes should be documented in here.

##  Version 11:

* Allow declaring storage features via plugin data

  A new `storage_has_feature()` helper function was added that checks a storage plugin's features.
  Plugins can indicate support for certain features in their `plugindata`. The first such feature is
  `backup-provider`, see below for more details. To declare support for this feature, return
  `features => { 'backup-provider' => 1 }` as part of the plugin data.

* Introduce new_backup_provider() plugin method

  Proxmox VE now supports a `Backup Provider API` that can be used to implement custom backup
  solutions tightly integrated in the Proxmox VE stack. See the `PVE::BackupProvider::Plugin::Base`
  module for detailed documentation. A backup provider also needs to implement an associated storage
  plugin for user-facing integration in Proxmox VE. Such a plugin needds to opt-in to the
  `backup-provider` feature (see above) and implement the new_backup_provider() method, returning a
  blessed reference to the backup provider class. The rest of the plugin methods, e.g. listing
  content, providing usage information, etc., follow the same API as usual.

* Allow declaring sensitive properties via plugin data

  A new `sensitive_properties()` helper function was added to get the list of sensitive properties
  a plugin uses via the plugin's `plugindata`. The sensitive properties are passed separately from
  other properties to the `on_add_hook()` and `on_update_hook()` methods and should not be written
  to the storage configuration file directly, but stored in the more restricted
  `/etc/pve/priv/storage` directory on the Proxmox Cluster File System. For example, to declare that
  a `ssh-private-key` property used by the plugin is sensitive, return
  `'sensitive-properties' => { 'ssh-private-key' => 1 }` as part of the plugin data. The list of
  sensitive properties was hard-coded previously, as `encryption-key`, `keyring`, `master-pubkey`,
  `password`. For backwards compatibility, this list is still used if a plugin doesn't declare its
  own sensitive properties.

##  Version 10:

* a new `rename_volume` method has been added

  Storage plugins with rename support need to enable
  the `rename` feature flag; e.g. in the `volume_has_feature` method.

* Replace `volume_snapshot_list` with `volume_snapshot_info`:

  `volume_snapshot_list` was used exclusively by replication and currently, replication is only
  allowed for the storage type `zfspool`. Thus, no external plugins should be affected by this
  change and `APIAGE` is *not* reset.

  `volume_snapshot_info` returns a hash with snapshot names as keys and `id` and `timestamp` data
  for each snapshot, rather than just an array of snaphsot names like `volume_snapshot_list` did.

* Add `blockers` parameter to `volume_rollback_is_possible`:

  The parameter *can* be used to return a list of snapshots that is currently preventing rollback.

* Replace get/update_volume_notes with generic get/update_volume_attribute

  falling back to the old implementation for notes until we reset APIAGE. the
  new method optionally also supports querying/setting a protected flag.

##  Version 9: (AGE resets to 0):

* volume_import_formats gets a new parameter *inserted*:

  Old signature:
      sub($plugin, $scfg, $storeid, $volname, $base_snapshot, $with_snapshots)
  New signature:
      sub($plugin, $scfg, $storeid, $volname, $snapshot, $base_snapshot, $with_snapshots)

  This is now the same as `volume_export_formats`.

  The same goes for calls to `PVE::Storage::volume_import_formats`, which now
  takes a `$snapshot` parameter in the same place.

* $with_snapshots *may* now be an array reference containing an ordered list of
  snapshots, but *may* also just be a boolean, and the contained list *may* be
  ignored, so it can still be treated as a boolean.