openstack/cinder
Code Issues Proposed changes
cinder/api-ref/source/v3/ext-backups.inc
Sean McGinnis fffdac20c2 api-ref: Make v3 enclosing objects consistent 
Some request details provided information about the other
JSON value while others didn't. To make things consistent
and to make sure API consumers understand how the requests
need to be structured, this adds missing instances. It also
reorders some parameter lists to be a little more logical,
so even though we can't show the nested nature of some of
these, it at least doesn't show inner values before outer
ones.

This also corrects many errors seen while going through
the API ref. This is by no means exhaustive, and is already
somewhat out of the scope for this patch, so it is expected
that there are some (many) cases that are not addressed by
this patch. Those will be fixed with ongoing effort in
future patches.

Partial-bug: #1713517
Change-Id: I30964ba8d829778fd01174d639d44ba07e4b77a6
2017-09-01 09:54:34 -05:00

428 lines
8.9 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
Backups (backups)
=================
A backup is a full copy of a volume stored in an external service.
The service can be configured. The only supported service is Object
Storage. A backup can subsequently be restored from the external
service to either the same volume that the backup was originally
taken from or to a new volume. Backup and restore operations can
only be carried out on volumes that are in an unattached and
available state.
When you create, list, or delete backups, these status values are
possible:
**Backup statuses**
+-----------------+---------------------------------------------+
| Status | Description |
+-----------------+---------------------------------------------+
| creating | The backup is being created. |
+-----------------+---------------------------------------------+
| available | The backup is ready to restore to a volume. |
+-----------------+---------------------------------------------+
| deleting | The backup is being deleted. |
+-----------------+---------------------------------------------+
| error | A backup error occurred. |
+-----------------+---------------------------------------------+
| restoring | The backup is being restored to a volume. |
+-----------------+---------------------------------------------+
| error_restoring | A backup restoration error occurred. |
+-----------------+---------------------------------------------+
If an error occurs, you can find more information about the error
in the ``fail_reason`` field for the backup.
List backups with detail
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups/detail
Lists Block Storage backups, with details, to which the project has access,
since v3.31 if non-admin users specify invalid filters in the url,
API will return bad request.
Normal response codes: 200
Error response codes: badRequest(400)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- sort: sort
- limit: limit
- offset: offset
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backups: backups
- status: status_4
- object_count: object_count
- fail_reason: fail_reason
- description: description
- links: links_1
- availability_zone: availability_zone
- created_at: created_at
- updated_at: updated_at
- name: name_1
- has_dependent_backups: has_dependent_backups
- volume_id: volume_id
- container: container
- size: size
- id: id_1
- is_incremental: is_incremental
- data_timestamp: data_timestamp
- snapshot_id: snapshot_id_2
- os-backup-project-attr:project_id: os-backup-project-attr:project_id
Response Example
----------------
.. literalinclude:: ./samples/backups-list-detailed-response.json
:language: javascript
Show backup detail
~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups/{backup_id}
Shows details for a backup.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup: backup
- status: status_4
- object_count: object_count
- container: container
- description: description
- links: links_1
- availability_zone: availability_zone
- created_at: created_at
- updated_at: updated_at
- name: name_1
- has_dependent_backups: has_dependent_backups
- volume_id: volume_id
- fail_reason: fail_reason
- size: size
- backup: backup
- id: id_1
- is_incremental: is_incremental
- data_timestamp: data_timestamp
- snapshot_id: snapshot_id_2
- os-backup-project-attr:project_id: os-backup-project-attr:project_id
Response Example
----------------
.. literalinclude:: ./samples/backup-show-response.json
:language: javascript
Delete a backup
~~~~~~~~~~~~~~~
.. rest_method:: DELETE /v3/{project_id}/backups/{backup_id}
Deletes a backup.
Normal response codes: 202,
Error response codes: Bad Request(400)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id
Restore a backup
~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/backups/{backup_id}/restore
Restores a Block Storage backup to an existing or new Block Storage volume.
You must specify either the UUID or name of the volume. If you
specify both the UUID and name, the UUID takes priority.
Normal response codes: 202,
Error response codes: Bad Request(400), Request Entity Too Large(413)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id
- restore: restore
- name: name_8
- volume_id: volume_id_6
Request Example
---------------
.. literalinclude:: ./samples/backup-restore-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- restore: restore
- backup_id: backup_id
- volume_id: volume_id
- volume_name: volume_name
Response Example
----------------
.. literalinclude:: ./samples/backup-restore-response.json
:language: javascript
Create a backup
~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/backups
Creates a Block Storage backup from a volume.
Normal response codes: 202,
Error response codes: Bad Request(400), Internal Server Error(500)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup: backup
- volume_id: volume_id_2
- container: container
- description: description
- incremental: incremental
- force: force
- name: name_optional
- snapshot_id: snapshot_id_3
- metadata: metadata_9
Request Example
---------------
.. literalinclude:: ./samples/backup-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup: backup
- id: id_1
- links: links_1
- name: name_1
Update a backup
~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/backups/{backup_id}
Update a Block Storage backup. This API is available since v3.9.
Normal response codes: 202
Error response codes: Bad Request(400)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id
- backup: backup
- description: description
- name: name_optional
- metadata: metadata_9
Request Example
---------------
.. literalinclude:: ./samples/backup-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup: backup
- id: id_1
- links: links_1
- name: name_1
Response Example
----------------
.. literalinclude:: ./samples/backup-update-response.json
:language: javascript
List backups for project
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups
Lists Block Storage backups to which the project has access,
since v3.31 if non-admin users specify invalid filters in the
url, API will return bad request.
Normal response codes: 200
Error response codes: badRequest(400)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- sort: sort
- limit: limit
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backups: backups
- id: id_1
- links: links_1
- name: name_1
Response Example
----------------
.. literalinclude:: ./samples/backups-list-response.json
:language: javascript
Export a backup
~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups/{backup_id}/export_record
Export information about a backup.
Normal response codes: 200
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup_service: backup_service
- backup_url: backup_url
Response Example
----------------
.. literalinclude:: ./samples/backup-record-export-response.json
:language: javascript
Import a backup
~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/backups/{backup_id}/import_record
Import information about a backup.
Normal response codes: 201
Error response codes: badRequest(400), serviceUnavailable(503)
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id
Request Example
---------------
.. literalinclude:: ./samples/backup-record-import-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: id_1
- links: links_1
- name: name_1
Response Example
----------------
.. literalinclude:: ./samples/backup-record-import-response.json
View Git Blame Copy Permalink