[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:

* 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:
	10
	11	* Replace `volume_snapshot_list` with `volume_snapshot_info`:
	12
	13	`volume_snapshot_list` was used exclusively by replication and currently, replication is only
	14	allowed for the storage type `zfspool`. Thus, no external plugins should be affected by this
	15	change and `APIAGE` is not reset.
	16
	17	`volume_snapshot_info` returns a hash with snapshot names as keys and `id` and `timestamp` data
	18	for each snapshot, rather than just an array of snaphsot names like `volume_snapshot_list` did.
	19
	20	* Add `blockers` parameter to `volume_rollback_is_possible`:
	21
	22	The parameter can be used to return a list of snapshots that is currently preventing rollback.
	23
93fbc019 FG	24	* Replace get/update_volume_notes with generic get/update_volume_attribute
	25
	26	falling back to the old implementation for notes until we reset APIAGE. the
	27	new method optionally also supports querying/setting a protected flag.
	28
3cc29a04 WB	29	## Version 9: (AGE resets to 0):
	30
	31	* volume_import_formats gets a new parameter inserted:
	32
	33	Old signature:
	34	sub($plugin, $scfg, $storeid, $volname, $base_snapshot, $with_snapshots)
	35	New signature:
	36	sub($plugin, $scfg, $storeid, $volname, $snapshot, $base_snapshot, $with_snapshots)
	37
	38	This is now the same as `volume_export_formats`.
	39
	40	The same goes for calls to `PVE::Storage::volume_import_formats`, which now
	41	takes a `$snapshot` parameter in the same place.
	42
	43	* $with_snapshots may now be an array reference containing an ordered list of
	44	snapshots, but may also just be a boolean, and the contained list may be
	45	ignored, so it can still be treated as a boolean.
a799f752	46