[pve-storage.git] / ApiChangeLog

# 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 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.
Commit	Line	Data
3cc29a04 WB	1	# API Versioning ChangeLog
	2
	3	Our API versioning contains an `APIVER` and an `APIAGE`.
	4	The `APIAGE` is the number of versions we're backward compatible with. (iow. things got added
	5	without breaking anything unaware of it.)
	6
	7	Future changes should be documented in here.
	8
a799f752 FE	9	## Version 10:
a799f752 FE	10
95dfa44c AL	11	* a new `rename_volume` method has been added
	12
	13	Storage plugins with rename support need to enable
	14	the `rename` feature flag; e.g. in the `volume_has_feature` method.
	15
a799f752 FE	16	* Replace `volume_snapshot_list` with `volume_snapshot_info`:
	17
	18	`volume_snapshot_list` was used exclusively by replication and currently, replication is only
	19	allowed for the storage type `zfspool`. Thus, no external plugins should be affected by this
	20	change and `APIAGE` is not reset.
	21
	22	`volume_snapshot_info` returns a hash with snapshot names as keys and `id` and `timestamp` data
	23	for each snapshot, rather than just an array of snaphsot names like `volume_snapshot_list` did.
	24
	25	* Add `blockers` parameter to `volume_rollback_is_possible`:
	26
	27	The parameter can be used to return a list of snapshots that is currently preventing rollback.
	28
93fbc019 FG	29	* Replace get/update_volume_notes with generic get/update_volume_attribute
	30
	31	falling back to the old implementation for notes until we reset APIAGE. the
	32	new method optionally also supports querying/setting a protected flag.
	33
3cc29a04 WB	34	## Version 9: (AGE resets to 0):
	35
	36	* volume_import_formats gets a new parameter inserted:
	37
	38	Old signature:
	39	sub($plugin, $scfg, $storeid, $volname, $base_snapshot, $with_snapshots)
	40	New signature:
	41	sub($plugin, $scfg, $storeid, $volname, $snapshot, $base_snapshot, $with_snapshots)
	42
	43	This is now the same as `volume_export_formats`.
	44
	45	The same goes for calls to `PVE::Storage::volume_import_formats`, which now
	46	takes a `$snapshot` parameter in the same place.
	47
	48	* $with_snapshots may now be an array reference containing an ordered list of
	49	snapshots, but may also just be a boolean, and the contained list may be
	50	ignored, so it can still be treated as a boolean.
a799f752	51