Add API document for share group [3/3]

This patch adds a new API document for share group snapshot.

Partial-Bug: 1724716
Change-Id: I832d264eb220027aad32937dc64a6ca428ee55a4
This commit is contained in:
zhongjun 2017-10-31 20:36:03 +08:00 committed by zhongjun
parent 3da1c7d4fb
commit cd77c128b0
11 changed files with 512 additions and 0 deletions

View File

@ -39,3 +39,4 @@ Shared File Systems API (EXPERIMENTAL)
.. include:: share-replicas.inc
.. include:: share-groups.inc
.. include:: share-group-types.inc
.. include:: share-group-snapshots.inc

View File

@ -0,0 +1,5 @@
{
"reset_status": {
"status": "error"
}
}

View File

@ -0,0 +1,7 @@
{
"share_group_snapshot": {
"share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
"name": "test"
"description": "test description"
}
}

View File

@ -0,0 +1,22 @@
{
"share_group_snapshot": {
"status": "creating",
"share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "bookmark"
}
],
"name": null,
"members": [],
"created_at": "2017-08-10T03:01:39.442509",
"project_id": "e23850eeb91d4fa3866af634223e454c",
"id": "46bf5875-58d6-4816-948f-8828423b0b9f",
"description": null
}
}

View File

@ -0,0 +1,22 @@
{
"share_group_snapshot": {
"status": "creating",
"share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "bookmark"
}
],
"name": null,
"members": [],
"created_at": "2017-08-10T03:01:39.442509",
"project_id": "e23850eeb91d4fa3866af634223e454c",
"id": "46bf5875-58d6-4816-948f-8828423b0b9f",
"description": null
}
}

View File

@ -0,0 +1,6 @@
{
"share_group_snapshot": {
"name": "update name",
"description": "update description"
}
}

View File

@ -0,0 +1,22 @@
{
"share_group_snapshot": {
"status": "creating",
"share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "bookmark"
}
],
"name": null,
"members": [],
"created_at": "2017-08-10T03:01:39.442509",
"project_id": "e23850eeb91d4fa3866af634223e454c",
"id": "46bf5875-58d6-4816-948f-8828423b0b9f",
"description": null
}
}

View File

@ -0,0 +1,44 @@
{
"share_group_snapshots": [
{
"status": "available",
"share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "bookmark"
}
],
"name": null,
"members": [],
"created_at": "2017-08-10T03:01:39.000000",
"project_id": "e23850eeb91d4fa3866af634223e454c",
"id": "46bf5875-58d6-4816-948f-8828423b0b9f",
"description": null
},
{
"status": "available",
"share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
"rel": "bookmark"
}
],
"name": null,
"members": [],
"created_at": "2017-08-10T03:01:28.000000",
"project_id": "e23850eeb91d4fa3866af634223e454c",
"id": "9d8ed9be-4454-4df0-b0ae-8360b623d93d",
"description": null
}
]
}

View File

@ -0,0 +1,22 @@
{
"share_group_snapshot_members": [
{
"status": "available",
"share_id": "406ea93b-32e9-4907-a117-148b3945749f",
"created_at": "2017-09-07T11:50:39.000000",
"share_proto": "NFS",
"share_size": 1,
"id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
"size": 1
},
{
"status": "available",
"share_id": "406ea93b-32e9-4907-a117-148b3945749f",
"created_at": "2015-09-07T11:50:39.000000",
"share_proto": "NFS",
"share_size": 1,
"id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
"size": 1
}
]
}

View File

@ -0,0 +1,18 @@
{
"share_group_snapshot": [
{
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
"rel": "bookmark"
}
],
"name": null,
"id": "46bf5875-58d6-4816-948f-8828423b0b9f",
}
]
}

View File

@ -0,0 +1,343 @@
.. -*- rst -*-
=======================================
Share group snapshots (since API v2.31)
=======================================
Use the shared file service to make snapshots of share groups. A share
group snapshot is a point-in-time, read-only copy of the data that is
contained in a share group. You can create, update, and delete
share group snapshots. After you create a share group snapshot, you
can create a share group from it.
You can update a share group snapshot to rename it, change its
description, or update its state.
As administrator, you can also reset the state of a group snapshot. Use
the ``policy.json`` file to grant permissions for these actions to other
roles.
.. note::
Share Group Snapshot APIs are part of the `experimental APIs
<http://developer.openstack.org/api-ref/shared-file-systems/#experimental-apis>`_.
List share group snapshots
==========================
.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots
Lists all share group snapshots.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- project_id: project_id
- all_tenants: all_tenants
- name: group_snapshot_name_query
- description: group_snapshot_description_query
- status: group_snapshot_status_query
- share_group_id: share_group_id_query
- limit: limit_query
- offset: offset
- sort_key: sort_key
- sort_dir: sort_dir
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_snapshot_id
- name: snapshot_name
- links: group_snapshot_links
Response example
----------------
.. literalinclude:: samples/share-group-snapshots-list-response.json
:language: javascript
List share group snapshots with details
=======================================
.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots/detail
Lists all share group snapshots with details.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- project_id: project_id
- all_tenants: all_tenants
- name: group_snapshot_name_query
- description: group_snapshot_description_query
- status: group_snapshot_status_query
- share_group_id: share_group_id_query
- limit: limit_query
- offset: offset
- sort_key: sort_key
- sort_dir: sort_dir
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_snapshot_id
- project_id: project_id
- status: group_snapshot_status_required
- share_group_id: share_group_id
- name: group_snapshot_name
- description: group_snapshot_description
- created_at: group_snapshot_created_at
- members: group_snapshot_members
- links: group_snapshot_links
Response example
----------------
.. literalinclude:: samples/share-group-snapshots-list-detailed-response.json
:language: javascript
List share group snapshots members
==================================
.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/members
Lists all share group snapshots members.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- group_snapshot_id: group_snapshot_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_snapshot_id
- created_at: snapshot_created_at
- project_id: project_id
- size: snapshot_size
- share_protocol: snapshot_share_protocol
- name: snapshot_name
- share_group_snapshot_id: group_snapshot_id
- share_id: snapshot_share_id
Response example
----------------
.. literalinclude:: samples/share-group-snapshots-list-members-response.json
:language: javascript
Show share group snapshot details
=================================
.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
Shows details for a share group snapshot.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- group_snapshot_id: group_snapshot_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_snapshot_id
- project_id: project_id
- status: group_snapshot_status_required
- share_group_id: share_group_id
- name: group_snapshot_name
- description: group_snapshot_description
- created_at: group_snapshot_created_at
- members: group_snapshot_members
- links: group_snapshot_links
Response example
----------------
.. literalinclude:: samples/share-group-snapshot-show-response.json
:language: javascript
Create share group snapshot
===========================
.. rest_method:: POST /v2/{tenant_id}/share-group-snapshots
Creates a snapshot from a share.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), unprocessableEntity(422)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- name: group_snapshot_name_option
- description: group_snapshot_description_option
- share_group_id: share_group_id
Request example
---------------
.. literalinclude:: samples/share-group-snapshot-create-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_snapshot_id
- project_id: project_id
- status: group_snapshot_status_required
- share_group_id: share_group_id
- name: group_snapshot_name
- description: group_snapshot_description
- created_at: group_snapshot_created_at
- members: group_snapshot_members
- links: group_snapshot_links
Response example
----------------
.. literalinclude:: samples/share-group-snapshot-create-response.json
:language: javascript
Reset share group snapshot state
================================
.. rest_method:: POST /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/action
Administrator only. Explicitly updates the state of a share group snapshot.
Use the ``policy.json`` file to grant permissions for this action
to other roles.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- group_snapshot_id: group_snapshot_id_path
- status: group_snapshot_status_required
Request example
---------------
.. literalinclude:: samples/snapshot-actions-reset-state-request.json
:language: javascript
Update share group snapshot
===========================
.. rest_method:: PUT /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
Updates a share group snapshot.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), unprocessableEntity(422)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- group_snapshot_id: group_snapshot_id_path
- name: group_snapshot_name_option
- description: group_snapshot_description_option
Request example
---------------
.. literalinclude:: samples/snapshot-update-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_snapshot_id
- project_id: project_id
- status: group_snapshot_status_required
- share_group_id: share_group_id
- name: group_snapshot_name
- description: group_snapshot_description
- created_at: group_snapshot_created_at
- members: group_snapshot_members
- links: group_snapshot_links
Response example
----------------
.. literalinclude:: samples/share-group-snapshot-update-response.json
:language: javascript
Delete share group snapshot
===========================
.. rest_method:: DELETE /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
Deletes a share group snapshot.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- group_snapshot_id: group_snapshot_id_path