openstack/manila
Code Issues Proposed changes

[api-ref] Refactor Manila snapshot API

Browse Source 
This patch makes the Manila snapshot API reference more readable
and maintainable.

Change-Id: If34bfb99852bcca61b65edc14ec98c859e995344
This commit is contained in:
Ha Van Tu 2016-09-26 15:11:48 +07:00 committed by Goutham Pacha Ravi
parent 360be9607e
commit b09faaf43e
4 changed files with 277 additions and 222 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
api-ref/source/os-share-manage.inc
View File

@ -63,7 +63,7 @@ Response parameters
- share_network_id: share_network_id - share_network_id: share_network_id
- export_locations: export_locations - export_locations: export_locations
- share_server_id: share_server_id - share_server_id: share_server_id
- snapshot_id: snapshot_id_3 - snapshot_id: snapshot_id_share_response
- id: id_4 - id: id_4
- size: size_2 - size: size_2
- share_type: share_type_1 - share_type: share_type_1

313
api-ref/source/parameters.yaml
View File

@ -92,7 +92,7 @@ share_type_id:
in: path in: path
required: true required: true
type: string type: string
snapshot_id_1: snapshot_id_path:
description: | description: |
The UUID of the snapshot. The UUID of the snapshot.
in: path in: path
@ -267,7 +267,6 @@ offset:
in: query in: query
required: false required: false
type: integer type: integer
offset_2: offset_2:
description: | description: |
The offset to define start point of consistency The offset to define start point of consistency
@ -346,7 +345,7 @@ share_type_id_2:
in: query in: query
required: false required: false
type: string type: string
snapshot_id_2: snapshot_id_share_response:
description: | description: |
The UUID of the snapshot that was used to create The UUID of the snapshot that was used to create
the share. the share.
@ -864,24 +863,6 @@ created_at_1:
in: body in: body
required: true required: true
type: string type: string
created_at_10:
description: |
The date and time stamp when the snapshot was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an
offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
in: body
required: true
type: string
created_at_11: created_at_11:
description: | description: |
The date and time stamp when the share server was created. The date and time stamp when the share server was created.
@ -1098,15 +1079,6 @@ display_description:
in: body in: body
required: false required: false
type: string type: string
display_description_1:
description: |
The snapshot description. The shared file
systems API supports the use of both ``name`` and ``display_name``
attributes, which are inherited attributes from the block storage
API.
in: body
required: false
type: string
display_description_2: display_description_2:
description: | description: |
The snapshot description. If you specify this The snapshot description. If you specify this
@ -1129,14 +1101,6 @@ display_name:
in: body in: body
required: false required: false
type: string type: string
display_name_1:
description: |
The snapshot name. The Shared File Systems API
supports the use of both ``name`` and ``display_name`` attributes,
which are inherited attributes from the Block Storage API.
in: body
required: false
type: string
display_name_2: display_name_2:
description: | description: |
The snapshot name. The shared file systems API The snapshot name. The shared file systems API
@ -1316,15 +1280,6 @@ force:
in: body in: body
required: false required: false
type: boolean type: boolean
force_1:
description: |
Indicates whether snapshot creation is enabled
when a share is busy. Set to ``true`` to force snapshot creation
when the share is busy. Set to ``false`` to deny snapshot
creation when the share is busy. Default is ``false``.
in: body
required: false
type: boolean
force_delete: force_delete:
description: | description: |
To force-delete a consistency group snapshot, set To force-delete a consistency group snapshot, set
@ -1355,14 +1310,6 @@ force_delete_3:
in: body in: body
required: true required: true
type: string type: string
force_delete_4:
description: |
To force-delete a snapshot, set this value to
``null``. The force- delete action, unlike the delete action,
ignores the snapshot status.
in: body
required: true
type: string
force_host_copy: force_host_copy:
description: | description: |
Enables or disables generic host-based forced Enables or disables generic host-based forced
@ -1371,6 +1318,15 @@ force_host_copy:
in: body in: body
required: true required: true
type: boolean type: boolean
force_snapshot_request:
description: |
Indicates whether snapshot creation must be attempted
when a share's status is not ``available``. Set to ``true`` to force
snapshot creation when the share is busy performing other operations.
Default is ``false``.
in: body
required: false
type: boolean
free_capacity_gb: free_capacity_gb:
description: | description: |
The amount of free capacity for the back end, in The amount of free capacity for the back end, in
@ -1995,19 +1951,13 @@ protocol:
in: body in: body
required: true required: true
type: string type: string
provider_location: provider_location_request:
description: |
(Since API v2.12) Provider location of the
snapshot on the backend.
in: body
required: true
type: string
provider_location_1:
description: | description: |
Provider location of the snapshot on the backend. Provider location of the snapshot on the backend.
in: body in: body
required: true required: false
type: string type: string
min_version: 2.12
qos: qos:
description: | description: |
The quality of service (QoS) support. The quality of service (QoS) support.
@ -2489,20 +2439,6 @@ share_id_4:
in: body in: body
required: true required: true
type: string type: string
share_id_5:
description: |
The UUID of the source share that was used to
create the snapshot.
in: body
required: true
type: string
share_id_6:
description: |
The UUID of the share that has snapshot which
should be managed.
in: body
required: true
type: string
share_id_7: share_id_7:
description: | description: |
The UUID of the share to which you are granted The UUID of the share to which you are granted
@ -2570,23 +2506,7 @@ share_proto:
description: | description: |
The Shared File Systems protocol. A valid value The Shared File Systems protocol. A valid value
is ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or ``CephFS``. is ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or ``CephFS``.
``CephFS`` supported starting with API v2.13 ``CephFS`` supported is starting with API v2.13.
in: body
required: true
type: string
share_proto_1:
description: |
The file system protocol of a share snapshot. A
valid value is ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or
``CephFS``. ``CephFS`` supported starting with API v2.13
in: body
required: true
type: string
share_proto_2:
description: |
The file system protocol of a share snapshot. A
valid value is ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or
``CephFS``. ``CephFS`` supported starting with API v2.13.
in: body in: body
required: true required: true
type: string type: string
@ -2603,12 +2523,6 @@ share_server_id:
in: body in: body
required: true required: true
type: string type: string
share_size:
description: |
The share snapshot size, in GBs.
in: body
required: true
type: integer
share_size_1: share_size_1:
description: | description: |
The size of a source share, in GBs. The size of a source share, in GBs.
@ -2690,22 +2604,175 @@ size_2:
in: body in: body
required: true required: true
type: integer type: integer
size_3: snapshot_created_at:
description: |
The date and time stamp when the snapshot was created.
The date and time stamp format is `ISO 8601
<https://en.wikipedia.org/wiki/ISO_8601>`_:
::
CCYY-MM-DDThh:mm:ss±hh:mm
The ``±hh:mm`` value, if included, returns the time zone as an
offset from UTC.
For example, ``2015-08-27T09:49:58-05:00``.
in: body
required: true
type: string
snapshot_description:
description: |
The snapshot description.
in: body
required: true
type: string
snapshot_description_request:
description: |
The snapshot description.
in: body
required: false
type: string
snapshot_display_description:
description: |
The snapshot description. The shared file
systems API supports the use of both ``name`` and ``display_name``
attributes, which are inherited attributes from the block storage
API.
in: body
required: false
type: string
snapshot_display_name:
description: |
The snapshot name. The Shared File Systems API
supports the use of both ``name`` and ``display_name`` attributes,
which are inherited attributes from the Block Storage API.
in: body
required: false
type: string
snapshot_force_delete:
description: |
To force-delete a snapshot, include this param and set its value to
``null``. The force-delete action, unlike the delete action,
ignores the snapshot status.
in: body
required: true
type: string
snapshot_id:
description: |
The UUID of the snapshot.
in: body
required: true
type: string
snapshot_id_query:
description: |
The UUID of the share's base snapshot to filter the request based on.
in: body
required: false
type: string
snapshot_id_request:
description: |
The UUID of the share's base snapshot.
in: body
required: false
type: string
snapshot_manage_share_id:
description: |
The UUID of the share that has snapshot which
should be managed.
in: body
required: true
type: string
snapshot_manage_status:
description: |
The snapshot status, which could be
``manage_starting``, ``manage_error``, ``unmanage_starting``, or
``unmanage_error``.
in: body
required: true
type: string
snapshot_name:
description: |
The snapshot name.
in: body
required: true
type: string
snapshot_name_request:
description: |
The snapshot name.
in: body
required: false
type: string
snapshot_provider_location:
description: |
Provider location of the snapshot on the backend.
in: body
required: true
type: string
snapshot_provider_location_request:
description: |
Provider location of the snapshot on the backend.
in: body
required: true
type: string
snapshot_share_id:
description: |
The UUID of the source share that was used to
create the snapshot.
in: body
required: true
type: string
snapshot_share_id_request:
description: |
The UUID of the share from which to create a
snapshot.
in: body
required: true
type: string
snapshot_share_protocol:
description: |
The file system protocol of a share snapshot. A
valid value is ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or
``CephFS``. ``CephFS`` is supported starting with API v2.13.
in: body
required: true
type: string
snapshot_share_protocol_request:
description: |
The file system protocol of a share snapshot. A
valid value is ``NFS``, ``CIFS``, ``GlusterFS``, ``HDFS``, or
``CephFS``. ``CephFS`` is supported starting with API v2.13.
in: body
required: true
type: string
snapshot_share_size:
description: |
The share snapshot size, in GBs.
in: body
required: true
type: integer
snapshot_size:
description: | description: |
The snapshot size, in GBs. The snapshot size, in GBs.
in: body in: body
required: true required: true
type: integer type: integer
snapshot_id: snapshot_status:
description: | description: |
The UUID of the snapshot from which to create the The snapshot status, which can be ``available``,
share. ``error``, ``creating``, ``deleting``, ``manage_starting``,
``manage_error``, ``unmanage_starting``, ``unmanage_error`` or
``error_deleting``.
in: body in: body
required: false requitred: true
type: string type: string
snapshot_id_3: snapshot_status_request:
description: | description: |
The UUID of the snapshot. The snapshot status, which can be ``available``,
``error``, ``creating``, ``deleting``, ``manage_starting``,
``manage_error``, ``unmanage_starting``, ``unmanage_error`` or
``error_deleting``.
in: body in: body
required: false required: false
type: string type: string
@ -2741,6 +2808,13 @@ snapshot_support_3:
in: body in: body
required: false required: false
type: boolean type: boolean
snapshot_unmanage:
description: |
To unmanage a share snapshot, include this parameter and set its value to
``null``.
in: body
required: true
type: string
source_cgsnapshot_id: source_cgsnapshot_id:
description: | description: |
The ID of the consistency group snapshot from The ID of the consistency group snapshot from
@ -2814,28 +2888,6 @@ status_11:
in: body in: body
required: true required: true
type: string type: string
status_12:
description: |
The snapshot status, which is ``available``,
``error``, ``creating``, ``deleting``, or ``error_deleting``.
in: body
required: false
type: string
status_13:
description: |
The snapshot status, which is ``available``,
``error``, ``creating``, ``deleting``, or ``error_deleting``.
in: body
required: true
type: string
status_14:
description: |
The snapshot status, which is
``manage_starting``, ``manage_error``, ``unmanage_starting``, or
``unmanage_error``.
in: body
required: true
type: string
status_15: status_15:
description: | description: |
The share server status, which is is ``active``, The share server status, which is is ``active``,
@ -3240,4 +3292,3 @@ zone:
in: body in: body
required: true required: true
type: string type: string

16
api-ref/source/shares.inc
View File

@ -93,7 +93,7 @@ Request
- offset: offset - offset: offset
- sort_key: sort_key - sort_key: sort_key
- sort_dir: sort_dir - sort_dir: sort_dir
- snapshot_id: snapshot_id_2 - snapshot_id: snapshot_id_query
- host: host_1 - host: host_1
- share_network_id: share_network_id - share_network_id: share_network_id
- project_id: project_id_6 - project_id: project_id_6
@ -144,7 +144,7 @@ Request
- offset: offset - offset: offset
- sort_key: sort_key - sort_key: sort_key
- sort_dir: sort_dir - sort_dir: sort_dir
- snapshot_id: snapshot_id_2 - snapshot_id: snapshot_id_query
- host: host_1 - host: host_1
- share_network_id: share_network_id - share_network_id: share_network_id
- project_id: project_id_6 - project_id: project_id_6
@ -162,7 +162,7 @@ Response parameters
- share_network_id: share_network_id - share_network_id: share_network_id
- export_locations: export_locations - export_locations: export_locations
- share_server_id: share_server_id - share_server_id: share_server_id
- snapshot_id: snapshot_id_3 - snapshot_id: snapshot_id_share_response
- id: id_4 - id: id_4
- size: size_2 - size: size_2
- share_type: share_type_1 - share_type: share_type_1
@ -223,7 +223,7 @@ Response parameters
- share_network_id: share_network_id - share_network_id: share_network_id
- export_locations: export_locations - export_locations: export_locations
- share_server_id: share_server_id - share_server_id: share_server_id
- snapshot_id: snapshot_id_3 - snapshot_id: snapshot_id_share_response
- id: id_4 - id: id_4
- size: size_2 - size: size_2
- share_type: share_type_1 - share_type: share_type_1
@ -278,7 +278,7 @@ Request
- display_description: display_description - display_description: display_description
- share_type: share_type - share_type: share_type
- volume_type: volume_type - volume_type: volume_type
- snapshot_id: snapshot_id - snapshot_id: snapshot_id_request
- is_public: is_public - is_public: is_public
- metadata: metadata - metadata: metadata
- share_network_id: share_network_id_2 - share_network_id: share_network_id_2
@ -311,7 +311,7 @@ Response parameters
- has_replicas: has_replicas - has_replicas: has_replicas
- replication_type: replication_type - replication_type: replication_type
- volume_type: volume_type - volume_type: volume_type
- snapshot_id: snapshot_id - snapshot_id: snapshot_id_share_response
- is_public: is_public - is_public: is_public
- metadata: metadata - metadata: metadata
- share_network_id: share_network_id - share_network_id: share_network_id
@ -378,7 +378,7 @@ Response parameters
- share_network_id: share_network_id - share_network_id: share_network_id
- export_locations: export_locations - export_locations: export_locations
- share_server_id: share_server_id - share_server_id: share_server_id
- snapshot_id: snapshot_id_3 - snapshot_id: snapshot_id_share_response
- id: id_4 - id: id_4
- size: size_2 - size: size_2
- share_type: share_type_1 - share_type: share_type_1
@ -458,7 +458,7 @@ Response parameters
- share_network_id: share_network_id - share_network_id: share_network_id
- export_locations: export_locations - export_locations: export_locations
- share_server_id: share_server_id - share_server_id: share_server_id
- snapshot_id: snapshot_id_3 - snapshot_id: snapshot_id_share_response
- id: id_4 - id: id_4
- size: size_2 - size: size_2
- share_type: share_type_1 - share_type: share_type_1

168
api-ref/source/snapshots.inc
View File

@ -51,15 +51,15 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
Response parameters Response parameters
------------------- -------------------
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- id: id_16 - id: snapshot_id
- name: name_15 - name: snapshot_name
Response example Response example
---------------- ----------------
@ -83,22 +83,22 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
Response parameters Response parameters
------------------- -------------------
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- id: id_16 - id: snapshot_id
- status: status_13 - status: snapshot_status
- share_id: share_id_5 - share_id: snapshot_share_id
- name: name_15 - name: snapshot_name
- description: description_11 - description: snapshot_description
- created_at: created_at_10 - created_at: snapshot_created_at
- share_proto: share_proto_2 - share_proto: snapshot_share_protocol
- share_size: share_size - share_size: snapshot_share_size
- size: size_3 - size: snapshot_size
Response example Response example
---------------- ----------------
@ -122,23 +122,23 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- snapshot_id: snapshot_id_1 - snapshot_id: snapshot_id_path
Response parameters Response parameters
------------------- -------------------
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- id: id_16 - id: snapshot_id
- status: status_13 - status: snapshot_status
- share_id: share_id_5 - share_id: snapshot_share_id
- name: name_15 - name: snapshot_name
- description: description_11 - description: snapshot_description
- created_at: created_at_10 - created_at: snapshot_created_at
- share_proto: share_proto_2 - share_proto: snapshot_share_protocol
- share_size: share_size - share_size: snapshot_share_size
- size: size_3 - size: snapshot_size
Response example Response example
---------------- ----------------
@ -164,13 +164,13 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- share_id: share_id_4 - share_id: snapshot_share_id_request
- force: force - force: force_snapshot_request
- name: name_14 - name: snapshot_name_request
- display_name: display_name_1 - display_name: snapshot_display_name
- description: description_10 - description: snapshot_description_request
- display_description: display_description_1 - display_description: snapshot_display_description
Request example Request example
--------------- ---------------
@ -183,16 +183,16 @@ Response parameters
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- id: id_16 - id: snapshot_id
- share_id: share_id_5 - share_id: snapshot_share_id
- status: status_13 - status: snapshot_status
- name: name_15 - name: snapshot_name
- description: description_11 - description: snapshot_description
- created_at: created_at_10 - created_at: snapshot_created_at
- share_proto: share_proto - share_proto: snapshot_share_protocol
- share_size: share_size - share_size: snapshot_share_size
- provider_location: provider_location_1 - provider_location: snapshot_provider_location
- size: size_3 - size: snapshot_size
Response example Response example
---------------- ----------------
@ -217,13 +217,13 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- share_id: share_id_6 - share_id: snapshot_manage_share_id
- provider_location: provider_location - provider_location: snapshot_provider_location_request
- name: name - name: snapshot_name_request
- display_name: display_name_1 - display_name: snapshot_display_name
- description: description - description: snapshot_description_request
- display_description: display_description_1 - display_description: snapshot_display_description
- driver_options: driver_options - driver_options: driver_options
Request example Request example
@ -237,16 +237,16 @@ Response parameters
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- id: id_16 - id: snapshot_id
- share_id: share_id_5 - share_id: snapshot_share_id
- status: status_14 - status: snapshot_manage_status
- name: name_15 - name: snapshot_name
- description: description_11 - description: snapshot_description
- created_at: created_at_10 - created_at: snapshot_created_at
- share_proto: share_proto - share_proto: snapshot_share_protocol
- share_size: share_size - share_size: snapshot_share_size
- provider_location: provider_location_1 - provider_location: snapshot_provider_location
- size: size_3 - size: snapshot_size
Response example Response example
---------------- ----------------
@ -271,9 +271,9 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- snapshot_id: snapshot_id_1 - snapshot_id: snapshot_id_path
- unmanage: unmanage - unmanage: snapshot_unmanage
Request example Request example
--------------- ---------------
@ -281,6 +281,10 @@ Request example
.. literalinclude:: samples/snapshot-actions-unmanage-request.json .. literalinclude:: samples/snapshot-actions-unmanage-request.json
:language: javascript :language: javascript
Response parameters
-------------------
There is no body content for the response.
Reset share snapshot state Reset share snapshot state
========================== ==========================
@ -301,9 +305,9 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- snapshot_id: snapshot_id_1 - snapshot_id: snapshot_id_path
- status: status_12 - status: snapshot_status_request
Request example Request example
--------------- ---------------
@ -331,9 +335,9 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- snapshot_id: snapshot_id_1 - snapshot_id: snapshot_id_path
- force_delete: force_delete_4 - force_delete: snapshot_force_delete
Request example Request example
--------------- ---------------
@ -371,10 +375,10 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- snapshot_id: snapshot_id_1 - snapshot_id: snapshot_id_path
- display_name: display_name_3 - display_name: snapshot_display_name
- display_description: display_description_2 - display_description: snapshot_display_description
Request example Request example
--------------- ---------------
@ -387,15 +391,15 @@ Response parameters
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- id: id_16 - id: snapshot_id
- status: status_13 - status: snapshot_status
- share_id: share_id_5 - share_id: snapshot_share_id
- name: name_15 - name: snapshot_name
- description: description_11 - description: snapshot_description
- created_at: created_at_10 - created_at: snapshot_created_at
- share_proto: share_proto_2 - share_proto: snapshot_share_protocol
- share_size: share_size - share_size: snapshot_share_size
- size: size_3 - size: snapshot_size
Response example Response example
---------------- ----------------
@ -420,5 +424,5 @@ Request
.. rest_parameters:: parameters.yaml .. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_1 - tenant_id: tenant_id_path
- snapshot_id: snapshot_id_1 - snapshot_id: snapshot_id_path