summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorzhongjun <jun.zhongjun@huawei.com>2017-10-31 20:36:03 +0800
committerzhongjun <jun.zhongjun2@gmail.com>2017-11-02 16:38:16 +0000
commitcd77c128b0bf9f0f9b64a4084ff85b8799be799b (patch)
tree4fbc7adaab7a03682d17e738975a74a873b85ece
parent3da1c7d4fbaae01a325854262a9ccc3789bbbc8f (diff)
Add API document for share group [3/3]6.0.0.0b1
This patch adds a new API document for share group snapshot. Partial-Bug: 1724716 Change-Id: I832d264eb220027aad32937dc64a6ca428ee55a4
Notes
Notes (review): Code-Review+2: Ben Swartzlander <ben@swartzlander.org> Workflow+1: Ben Swartzlander <ben@swartzlander.org> Verified+2: Zuul Submitted-by: Zuul Submitted-at: Thu, 02 Nov 2017 18:10:06 +0000 Reviewed-on: https://review.openstack.org/516659 Project: openstack/manila Branch: refs/heads/master
-rw-r--r--api-ref/source/index.rst1
-rw-r--r--api-ref/source/samples/share-group-snapshot-actions-reset-state-request.json5
-rw-r--r--api-ref/source/samples/share-group-snapshot-create-request.json7
-rw-r--r--api-ref/source/samples/share-group-snapshot-create-response.json22
-rw-r--r--api-ref/source/samples/share-group-snapshot-show-response.json22
-rw-r--r--api-ref/source/samples/share-group-snapshot-update-request.json6
-rw-r--r--api-ref/source/samples/share-group-snapshot-update-response.json22
-rw-r--r--api-ref/source/samples/share-group-snapshots-list-detailed-response.json44
-rw-r--r--api-ref/source/samples/share-group-snapshots-list-members-response.json22
-rw-r--r--api-ref/source/samples/share-group-snapshots-list-response.json18
-rw-r--r--api-ref/source/share-group-snapshots.inc343
11 files changed, 512 insertions, 0 deletions
diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index 8cd753f..1f47ea4 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -39,3 +39,4 @@ Shared File Systems API (EXPERIMENTAL)
39.. include:: share-replicas.inc 39.. include:: share-replicas.inc
40.. include:: share-groups.inc 40.. include:: share-groups.inc
41.. include:: share-group-types.inc 41.. include:: share-group-types.inc
42.. include:: share-group-snapshots.inc
diff --git a/api-ref/source/samples/share-group-snapshot-actions-reset-state-request.json b/api-ref/source/samples/share-group-snapshot-actions-reset-state-request.json
new file mode 100644
index 0000000..e5f70b3
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshot-actions-reset-state-request.json
@@ -0,0 +1,5 @@
1{
2 "reset_status": {
3 "status": "error"
4 }
5}
diff --git a/api-ref/source/samples/share-group-snapshot-create-request.json b/api-ref/source/samples/share-group-snapshot-create-request.json
new file mode 100644
index 0000000..5e97706
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshot-create-request.json
@@ -0,0 +1,7 @@
1{
2 "share_group_snapshot": {
3 "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
4 "name": "test"
5 "description": "test description"
6 }
7}
diff --git a/api-ref/source/samples/share-group-snapshot-create-response.json b/api-ref/source/samples/share-group-snapshot-create-response.json
new file mode 100644
index 0000000..386fe86
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshot-create-response.json
@@ -0,0 +1,22 @@
1{
2 "share_group_snapshot": {
3 "status": "creating",
4 "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
5 "links": [
6 {
7 "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
8 "rel": "self"
9 },
10 {
11 "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
12 "rel": "bookmark"
13 }
14 ],
15 "name": null,
16 "members": [],
17 "created_at": "2017-08-10T03:01:39.442509",
18 "project_id": "e23850eeb91d4fa3866af634223e454c",
19 "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
20 "description": null
21 }
22}
diff --git a/api-ref/source/samples/share-group-snapshot-show-response.json b/api-ref/source/samples/share-group-snapshot-show-response.json
new file mode 100644
index 0000000..386fe86
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshot-show-response.json
@@ -0,0 +1,22 @@
1{
2 "share_group_snapshot": {
3 "status": "creating",
4 "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
5 "links": [
6 {
7 "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
8 "rel": "self"
9 },
10 {
11 "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
12 "rel": "bookmark"
13 }
14 ],
15 "name": null,
16 "members": [],
17 "created_at": "2017-08-10T03:01:39.442509",
18 "project_id": "e23850eeb91d4fa3866af634223e454c",
19 "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
20 "description": null
21 }
22}
diff --git a/api-ref/source/samples/share-group-snapshot-update-request.json b/api-ref/source/samples/share-group-snapshot-update-request.json
new file mode 100644
index 0000000..fc704cc
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshot-update-request.json
@@ -0,0 +1,6 @@
1{
2 "share_group_snapshot": {
3 "name": "update name",
4 "description": "update description"
5 }
6}
diff --git a/api-ref/source/samples/share-group-snapshot-update-response.json b/api-ref/source/samples/share-group-snapshot-update-response.json
new file mode 100644
index 0000000..386fe86
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshot-update-response.json
@@ -0,0 +1,22 @@
1{
2 "share_group_snapshot": {
3 "status": "creating",
4 "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
5 "links": [
6 {
7 "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
8 "rel": "self"
9 },
10 {
11 "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
12 "rel": "bookmark"
13 }
14 ],
15 "name": null,
16 "members": [],
17 "created_at": "2017-08-10T03:01:39.442509",
18 "project_id": "e23850eeb91d4fa3866af634223e454c",
19 "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
20 "description": null
21 }
22}
diff --git a/api-ref/source/samples/share-group-snapshots-list-detailed-response.json b/api-ref/source/samples/share-group-snapshots-list-detailed-response.json
new file mode 100644
index 0000000..eb396ea
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshots-list-detailed-response.json
@@ -0,0 +1,44 @@
1{
2 "share_group_snapshots": [
3 {
4 "status": "available",
5 "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
6 "links": [
7 {
8 "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
9 "rel": "self"
10 },
11 {
12 "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
13 "rel": "bookmark"
14 }
15 ],
16 "name": null,
17 "members": [],
18 "created_at": "2017-08-10T03:01:39.000000",
19 "project_id": "e23850eeb91d4fa3866af634223e454c",
20 "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
21 "description": null
22 },
23 {
24 "status": "available",
25 "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
26 "links": [
27 {
28 "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
29 "rel": "self"
30 },
31 {
32 "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
33 "rel": "bookmark"
34 }
35 ],
36 "name": null,
37 "members": [],
38 "created_at": "2017-08-10T03:01:28.000000",
39 "project_id": "e23850eeb91d4fa3866af634223e454c",
40 "id": "9d8ed9be-4454-4df0-b0ae-8360b623d93d",
41 "description": null
42 }
43 ]
44}
diff --git a/api-ref/source/samples/share-group-snapshots-list-members-response.json b/api-ref/source/samples/share-group-snapshots-list-members-response.json
new file mode 100644
index 0000000..c09d5cd
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshots-list-members-response.json
@@ -0,0 +1,22 @@
1{
2 "share_group_snapshot_members": [
3 {
4 "status": "available",
5 "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
6 "created_at": "2017-09-07T11:50:39.000000",
7 "share_proto": "NFS",
8 "share_size": 1,
9 "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
10 "size": 1
11 },
12 {
13 "status": "available",
14 "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
15 "created_at": "2015-09-07T11:50:39.000000",
16 "share_proto": "NFS",
17 "share_size": 1,
18 "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
19 "size": 1
20 }
21 ]
22}
diff --git a/api-ref/source/samples/share-group-snapshots-list-response.json b/api-ref/source/samples/share-group-snapshots-list-response.json
new file mode 100644
index 0000000..8a18184
--- /dev/null
+++ b/api-ref/source/samples/share-group-snapshots-list-response.json
@@ -0,0 +1,18 @@
1{
2 "share_group_snapshot": [
3 {
4 "links": [
5 {
6 "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
7 "rel": "self"
8 },
9 {
10 "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
11 "rel": "bookmark"
12 }
13 ],
14 "name": null,
15 "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
16 }
17 ]
18}
diff --git a/api-ref/source/share-group-snapshots.inc b/api-ref/source/share-group-snapshots.inc
new file mode 100644
index 0000000..2d70d95
--- /dev/null
+++ b/api-ref/source/share-group-snapshots.inc
@@ -0,0 +1,343 @@
1.. -*- rst -*-
2
3=======================================
4Share group snapshots (since API v2.31)
5=======================================
6
7Use the shared file service to make snapshots of share groups. A share
8group snapshot is a point-in-time, read-only copy of the data that is
9contained in a share group. You can create, update, and delete
10share group snapshots. After you create a share group snapshot, you
11can create a share group from it.
12
13You can update a share group snapshot to rename it, change its
14description, or update its state.
15
16As administrator, you can also reset the state of a group snapshot. Use
17the ``policy.json`` file to grant permissions for these actions to other
18roles.
19
20.. note::
21
22 Share Group Snapshot APIs are part of the `experimental APIs
23 <http://developer.openstack.org/api-ref/shared-file-systems/#experimental-apis>`_.
24
25List share group snapshots
26==========================
27
28.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots
29
30Lists all share group snapshots.
31
32Normal response codes: 200
33Error response codes: badRequest(400), unauthorized(401)
34
35Request
36-------
37
38.. rest_parameters:: parameters.yaml
39
40 - tenant_id: tenant_id_path
41 - project_id: project_id
42 - all_tenants: all_tenants
43 - name: group_snapshot_name_query
44 - description: group_snapshot_description_query
45 - status: group_snapshot_status_query
46 - share_group_id: share_group_id_query
47 - limit: limit_query
48 - offset: offset
49 - sort_key: sort_key
50 - sort_dir: sort_dir
51
52Response parameters
53-------------------
54
55.. rest_parameters:: parameters.yaml
56
57 - id: group_snapshot_id
58 - name: snapshot_name
59 - links: group_snapshot_links
60
61Response example
62----------------
63
64.. literalinclude:: samples/share-group-snapshots-list-response.json
65 :language: javascript
66
67
68List share group snapshots with details
69=======================================
70
71.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots/detail
72
73Lists all share group snapshots with details.
74
75Normal response codes: 200
76Error response codes: badRequest(400), unauthorized(401)
77
78Request
79-------
80
81.. rest_parameters:: parameters.yaml
82
83 - tenant_id: tenant_id_path
84 - project_id: project_id
85 - all_tenants: all_tenants
86 - name: group_snapshot_name_query
87 - description: group_snapshot_description_query
88 - status: group_snapshot_status_query
89 - share_group_id: share_group_id_query
90 - limit: limit_query
91 - offset: offset
92 - sort_key: sort_key
93 - sort_dir: sort_dir
94
95Response parameters
96-------------------
97
98.. rest_parameters:: parameters.yaml
99
100 - id: group_snapshot_id
101 - project_id: project_id
102 - status: group_snapshot_status_required
103 - share_group_id: share_group_id
104 - name: group_snapshot_name
105 - description: group_snapshot_description
106 - created_at: group_snapshot_created_at
107 - members: group_snapshot_members
108 - links: group_snapshot_links
109
110Response example
111----------------
112
113.. literalinclude:: samples/share-group-snapshots-list-detailed-response.json
114 :language: javascript
115
116
117List share group snapshots members
118==================================
119
120.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/members
121
122Lists all share group snapshots members.
123
124Normal response codes: 200
125Error response codes: badRequest(400), unauthorized(401)
126
127Request
128-------
129
130.. rest_parameters:: parameters.yaml
131
132 - tenant_id: tenant_id_path
133 - group_snapshot_id: group_snapshot_id_path
134
135Response parameters
136-------------------
137
138.. rest_parameters:: parameters.yaml
139
140 - id: group_snapshot_id
141 - created_at: snapshot_created_at
142 - project_id: project_id
143 - size: snapshot_size
144 - share_protocol: snapshot_share_protocol
145 - name: snapshot_name
146 - share_group_snapshot_id: group_snapshot_id
147 - share_id: snapshot_share_id
148
149
150Response example
151----------------
152
153.. literalinclude:: samples/share-group-snapshots-list-members-response.json
154 :language: javascript
155
156
157Show share group snapshot details
158=================================
159
160.. rest_method:: GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
161
162Shows details for a share group snapshot.
163
164Normal response codes: 200
165Error response codes: badRequest(400), unauthorized(401), itemNotFound(404)
166
167Request
168-------
169
170.. rest_parameters:: parameters.yaml
171
172 - tenant_id: tenant_id_path
173 - group_snapshot_id: group_snapshot_id_path
174
175Response parameters
176-------------------
177
178.. rest_parameters:: parameters.yaml
179
180 - id: group_snapshot_id
181 - project_id: project_id
182 - status: group_snapshot_status_required
183 - share_group_id: share_group_id
184 - name: group_snapshot_name
185 - description: group_snapshot_description
186 - created_at: group_snapshot_created_at
187 - members: group_snapshot_members
188 - links: group_snapshot_links
189
190Response example
191----------------
192
193.. literalinclude:: samples/share-group-snapshot-show-response.json
194 :language: javascript
195
196
197Create share group snapshot
198===========================
199
200.. rest_method:: POST /v2/{tenant_id}/share-group-snapshots
201
202Creates a snapshot from a share.
203
204
205Normal response codes: 200
206Error response codes: badRequest(400), unauthorized(401), forbidden(403),
207itemNotFound(404), unprocessableEntity(422)
208
209Request
210-------
211
212.. rest_parameters:: parameters.yaml
213
214 - tenant_id: tenant_id_path
215 - name: group_snapshot_name_option
216 - description: group_snapshot_description_option
217 - share_group_id: share_group_id
218
219Request example
220---------------
221
222.. literalinclude:: samples/share-group-snapshot-create-request.json
223 :language: javascript
224
225Response parameters
226-------------------
227
228.. rest_parameters:: parameters.yaml
229
230 - id: group_snapshot_id
231 - project_id: project_id
232 - status: group_snapshot_status_required
233 - share_group_id: share_group_id
234 - name: group_snapshot_name
235 - description: group_snapshot_description
236 - created_at: group_snapshot_created_at
237 - members: group_snapshot_members
238 - links: group_snapshot_links
239
240Response example
241----------------
242
243.. literalinclude:: samples/share-group-snapshot-create-response.json
244 :language: javascript
245
246
247Reset share group snapshot state
248================================
249
250.. rest_method:: POST /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/action
251
252Administrator only. Explicitly updates the state of a share group snapshot.
253
254Use the ``policy.json`` file to grant permissions for this action
255to other roles.
256
257Normal response codes: 202
258Error response codes: badRequest(400), unauthorized(401), forbidden(403),
259itemNotFound(404)
260
261Request
262-------
263
264.. rest_parameters:: parameters.yaml
265
266 - tenant_id: tenant_id_path
267 - group_snapshot_id: group_snapshot_id_path
268 - status: group_snapshot_status_required
269
270Request example
271---------------
272
273.. literalinclude:: samples/snapshot-actions-reset-state-request.json
274 :language: javascript
275
276
277Update share group snapshot
278===========================
279
280.. rest_method:: PUT /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
281
282Updates a share group snapshot.
283
284Normal response codes: 200
285Error response codes: badRequest(400), unauthorized(401), forbidden(403),
286itemNotFound(404), unprocessableEntity(422)
287
288Request
289-------
290
291.. rest_parameters:: parameters.yaml
292
293 - tenant_id: tenant_id_path
294 - group_snapshot_id: group_snapshot_id_path
295 - name: group_snapshot_name_option
296 - description: group_snapshot_description_option
297
298Request example
299---------------
300
301.. literalinclude:: samples/snapshot-update-request.json
302 :language: javascript
303
304Response parameters
305-------------------
306
307.. rest_parameters:: parameters.yaml
308
309 - id: group_snapshot_id
310 - project_id: project_id
311 - status: group_snapshot_status_required
312 - share_group_id: share_group_id
313 - name: group_snapshot_name
314 - description: group_snapshot_description
315 - created_at: group_snapshot_created_at
316 - members: group_snapshot_members
317 - links: group_snapshot_links
318
319Response example
320----------------
321
322.. literalinclude:: samples/share-group-snapshot-update-response.json
323 :language: javascript
324
325
326Delete share group snapshot
327===========================
328
329.. rest_method:: DELETE /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
330
331Deletes a share group snapshot.
332
333Normal response codes: 202
334Error response codes: badRequest(400), unauthorized(401), forbidden(403),
335itemNotFound(404)
336
337Request
338-------
339
340.. rest_parameters:: parameters.yaml
341
342 - tenant_id: tenant_id_path
343 - group_snapshot_id: group_snapshot_id_path