From b09faaf43ec777a2c0f8ab90600120841f8ae457 Mon Sep 17 00:00:00 2001 From: Ha Van Tu Date: Mon, 26 Sep 2016 15:11:48 +0700 Subject: [PATCH] [api-ref] Refactor Manila snapshot API This patch makes the Manila snapshot API reference more readable and maintainable. Change-Id: If34bfb99852bcca61b65edc14ec98c859e995344 --- api-ref/source/os-share-manage.inc | 2 +- api-ref/source/parameters.yaml | 313 +++++++++++++++++------------ api-ref/source/shares.inc | 16 +- api-ref/source/snapshots.inc | 168 ++++++++-------- 4 files changed, 277 insertions(+), 222 deletions(-) diff --git a/api-ref/source/os-share-manage.inc b/api-ref/source/os-share-manage.inc index e8f3d1270b..f58985c48e 100644 --- a/api-ref/source/os-share-manage.inc +++ b/api-ref/source/os-share-manage.inc @@ -63,7 +63,7 @@ Response parameters - share_network_id: share_network_id - export_locations: export_locations - share_server_id: share_server_id - - snapshot_id: snapshot_id_3 + - snapshot_id: snapshot_id_share_response - id: id_4 - size: size_2 - share_type: share_type_1 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index d1254eb5fe..a03a7264b8 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -92,7 +92,7 @@ share_type_id: in: path required: true type: string -snapshot_id_1: +snapshot_id_path: description: | The UUID of the snapshot. in: path @@ -267,7 +267,6 @@ offset: in: query required: false type: integer - offset_2: description: | The offset to define start point of consistency @@ -346,7 +345,7 @@ share_type_id_2: in: query required: false type: string -snapshot_id_2: +snapshot_id_share_response: description: | The UUID of the snapshot that was used to create the share. @@ -864,24 +863,6 @@ created_at_1: in: body required: true 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 - `_: - - :: - - 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: description: | The date and time stamp when the share server was created. @@ -1098,15 +1079,6 @@ display_description: in: body required: false 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: description: | The snapshot description. If you specify this @@ -1129,14 +1101,6 @@ display_name: in: body required: false 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: description: | The snapshot name. The shared file systems API @@ -1316,15 +1280,6 @@ force: in: body required: false 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: description: | To force-delete a consistency group snapshot, set @@ -1355,14 +1310,6 @@ force_delete_3: in: body required: true 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: description: | Enables or disables generic host-based forced @@ -1371,6 +1318,15 @@ force_host_copy: in: body required: true 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: description: | The amount of free capacity for the back end, in @@ -1995,19 +1951,13 @@ protocol: in: body required: true type: string -provider_location: - description: | - (Since API v2.12) Provider location of the - snapshot on the backend. - in: body - required: true - type: string -provider_location_1: +provider_location_request: description: | Provider location of the snapshot on the backend. in: body - required: true + required: false type: string + min_version: 2.12 qos: description: | The quality of service (QoS) support. @@ -2489,20 +2439,6 @@ share_id_4: in: body required: true 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: description: | The UUID of the share to which you are granted @@ -2570,23 +2506,7 @@ share_proto: description: | The Shared File Systems protocol. 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_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. + ``CephFS`` supported is starting with API v2.13. in: body required: true type: string @@ -2603,12 +2523,6 @@ share_server_id: in: body required: true type: string -share_size: - description: | - The share snapshot size, in GBs. - in: body - required: true - type: integer share_size_1: description: | The size of a source share, in GBs. @@ -2690,22 +2604,175 @@ size_2: in: body required: true 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 + `_: + + :: + + 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: | The snapshot size, in GBs. in: body required: true type: integer -snapshot_id: +snapshot_status: description: | - The UUID of the snapshot from which to create the - share. + The snapshot status, which can be ``available``, + ``error``, ``creating``, ``deleting``, ``manage_starting``, + ``manage_error``, ``unmanage_starting``, ``unmanage_error`` or + ``error_deleting``. in: body - required: false + requitred: true type: string -snapshot_id_3: +snapshot_status_request: 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 required: false type: string @@ -2741,6 +2808,13 @@ snapshot_support_3: in: body required: false 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: description: | The ID of the consistency group snapshot from @@ -2814,28 +2888,6 @@ status_11: in: body required: true 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: description: | The share server status, which is is ``active``, @@ -3240,4 +3292,3 @@ zone: in: body required: true type: string - diff --git a/api-ref/source/shares.inc b/api-ref/source/shares.inc index ad7830e006..d0aa77ab62 100644 --- a/api-ref/source/shares.inc +++ b/api-ref/source/shares.inc @@ -93,7 +93,7 @@ Request - offset: offset - sort_key: sort_key - sort_dir: sort_dir - - snapshot_id: snapshot_id_2 + - snapshot_id: snapshot_id_query - host: host_1 - share_network_id: share_network_id - project_id: project_id_6 @@ -144,7 +144,7 @@ Request - offset: offset - sort_key: sort_key - sort_dir: sort_dir - - snapshot_id: snapshot_id_2 + - snapshot_id: snapshot_id_query - host: host_1 - share_network_id: share_network_id - project_id: project_id_6 @@ -162,7 +162,7 @@ Response parameters - share_network_id: share_network_id - export_locations: export_locations - share_server_id: share_server_id - - snapshot_id: snapshot_id_3 + - snapshot_id: snapshot_id_share_response - id: id_4 - size: size_2 - share_type: share_type_1 @@ -223,7 +223,7 @@ Response parameters - share_network_id: share_network_id - export_locations: export_locations - share_server_id: share_server_id - - snapshot_id: snapshot_id_3 + - snapshot_id: snapshot_id_share_response - id: id_4 - size: size_2 - share_type: share_type_1 @@ -278,7 +278,7 @@ Request - display_description: display_description - share_type: share_type - volume_type: volume_type - - snapshot_id: snapshot_id + - snapshot_id: snapshot_id_request - is_public: is_public - metadata: metadata - share_network_id: share_network_id_2 @@ -311,7 +311,7 @@ Response parameters - has_replicas: has_replicas - replication_type: replication_type - volume_type: volume_type - - snapshot_id: snapshot_id + - snapshot_id: snapshot_id_share_response - is_public: is_public - metadata: metadata - share_network_id: share_network_id @@ -378,7 +378,7 @@ Response parameters - share_network_id: share_network_id - export_locations: export_locations - share_server_id: share_server_id - - snapshot_id: snapshot_id_3 + - snapshot_id: snapshot_id_share_response - id: id_4 - size: size_2 - share_type: share_type_1 @@ -458,7 +458,7 @@ Response parameters - share_network_id: share_network_id - export_locations: export_locations - share_server_id: share_server_id - - snapshot_id: snapshot_id_3 + - snapshot_id: snapshot_id_share_response - id: id_4 - size: size_2 - share_type: share_type_1 diff --git a/api-ref/source/snapshots.inc b/api-ref/source/snapshots.inc index 7cfbe389a2..8e058f80d7 100644 --- a/api-ref/source/snapshots.inc +++ b/api-ref/source/snapshots.inc @@ -51,15 +51,15 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 + - tenant_id: tenant_id_path Response parameters ------------------- .. rest_parameters:: parameters.yaml - - id: id_16 - - name: name_15 + - id: snapshot_id + - name: snapshot_name Response example ---------------- @@ -83,22 +83,22 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 + - tenant_id: tenant_id_path Response parameters ------------------- .. rest_parameters:: parameters.yaml - - id: id_16 - - status: status_13 - - share_id: share_id_5 - - name: name_15 - - description: description_11 - - created_at: created_at_10 - - share_proto: share_proto_2 - - share_size: share_size - - size: size_3 + - id: snapshot_id + - status: snapshot_status + - share_id: snapshot_share_id + - name: snapshot_name + - description: snapshot_description + - created_at: snapshot_created_at + - share_proto: snapshot_share_protocol + - share_size: snapshot_share_size + - size: snapshot_size Response example ---------------- @@ -122,23 +122,23 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - snapshot_id: snapshot_id_1 + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_path Response parameters ------------------- .. rest_parameters:: parameters.yaml - - id: id_16 - - status: status_13 - - share_id: share_id_5 - - name: name_15 - - description: description_11 - - created_at: created_at_10 - - share_proto: share_proto_2 - - share_size: share_size - - size: size_3 + - id: snapshot_id + - status: snapshot_status + - share_id: snapshot_share_id + - name: snapshot_name + - description: snapshot_description + - created_at: snapshot_created_at + - share_proto: snapshot_share_protocol + - share_size: snapshot_share_size + - size: snapshot_size Response example ---------------- @@ -164,13 +164,13 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - share_id: share_id_4 - - force: force - - name: name_14 - - display_name: display_name_1 - - description: description_10 - - display_description: display_description_1 + - tenant_id: tenant_id_path + - share_id: snapshot_share_id_request + - force: force_snapshot_request + - name: snapshot_name_request + - display_name: snapshot_display_name + - description: snapshot_description_request + - display_description: snapshot_display_description Request example --------------- @@ -183,16 +183,16 @@ Response parameters .. rest_parameters:: parameters.yaml - - id: id_16 - - share_id: share_id_5 - - status: status_13 - - name: name_15 - - description: description_11 - - created_at: created_at_10 - - share_proto: share_proto - - share_size: share_size - - provider_location: provider_location_1 - - size: size_3 + - id: snapshot_id + - share_id: snapshot_share_id + - status: snapshot_status + - name: snapshot_name + - description: snapshot_description + - created_at: snapshot_created_at + - share_proto: snapshot_share_protocol + - share_size: snapshot_share_size + - provider_location: snapshot_provider_location + - size: snapshot_size Response example ---------------- @@ -217,13 +217,13 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - share_id: share_id_6 - - provider_location: provider_location - - name: name - - display_name: display_name_1 - - description: description - - display_description: display_description_1 + - tenant_id: tenant_id_path + - share_id: snapshot_manage_share_id + - provider_location: snapshot_provider_location_request + - name: snapshot_name_request + - display_name: snapshot_display_name + - description: snapshot_description_request + - display_description: snapshot_display_description - driver_options: driver_options Request example @@ -237,16 +237,16 @@ Response parameters .. rest_parameters:: parameters.yaml - - id: id_16 - - share_id: share_id_5 - - status: status_14 - - name: name_15 - - description: description_11 - - created_at: created_at_10 - - share_proto: share_proto - - share_size: share_size - - provider_location: provider_location_1 - - size: size_3 + - id: snapshot_id + - share_id: snapshot_share_id + - status: snapshot_manage_status + - name: snapshot_name + - description: snapshot_description + - created_at: snapshot_created_at + - share_proto: snapshot_share_protocol + - share_size: snapshot_share_size + - provider_location: snapshot_provider_location + - size: snapshot_size Response example ---------------- @@ -271,9 +271,9 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - snapshot_id: snapshot_id_1 - - unmanage: unmanage + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_path + - unmanage: snapshot_unmanage Request example --------------- @@ -281,6 +281,10 @@ Request example .. literalinclude:: samples/snapshot-actions-unmanage-request.json :language: javascript +Response parameters +------------------- + +There is no body content for the response. Reset share snapshot state ========================== @@ -301,9 +305,9 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - snapshot_id: snapshot_id_1 - - status: status_12 + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_path + - status: snapshot_status_request Request example --------------- @@ -331,9 +335,9 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - snapshot_id: snapshot_id_1 - - force_delete: force_delete_4 + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_path + - force_delete: snapshot_force_delete Request example --------------- @@ -371,10 +375,10 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - snapshot_id: snapshot_id_1 - - display_name: display_name_3 - - display_description: display_description_2 + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_path + - display_name: snapshot_display_name + - display_description: snapshot_display_description Request example --------------- @@ -387,15 +391,15 @@ Response parameters .. rest_parameters:: parameters.yaml - - id: id_16 - - status: status_13 - - share_id: share_id_5 - - name: name_15 - - description: description_11 - - created_at: created_at_10 - - share_proto: share_proto_2 - - share_size: share_size - - size: size_3 + - id: snapshot_id + - status: snapshot_status + - share_id: snapshot_share_id + - name: snapshot_name + - description: snapshot_description + - created_at: snapshot_created_at + - share_proto: snapshot_share_protocol + - share_size: snapshot_share_size + - size: snapshot_size Response example ---------------- @@ -420,5 +424,5 @@ Request .. rest_parameters:: parameters.yaml - - tenant_id: tenant_id_1 - - snapshot_id: snapshot_id_1 + - tenant_id: tenant_id_path + - snapshot_id: snapshot_id_path