manila/api-ref/source/share-group-types.inc
Goutham Pacha Ravi e5582cc5a6 [api-ref] Use relative links and fix grammar
When referring to documents that are published
from the same folder, we can use relative links.

Change-Id: I431e20713e1b91be3bf9fa2f57a9c9b88519d6b4
2019-07-22 12:50:43 -07:00

484 lines
9.4 KiB
ReStructuredText

.. -*- rst -*-
===================================
Share group types (since API v2.31)
===================================
A share group type enables you to filter or choose back ends before you
create a share group.
You can set share group types as either public or private. By default a
share group type is created as publicly accessible. Set
``share_group_type_access:is_public`` to ``False`` to make a share group
type private.
You can manage access to the private share group types for different
projects. You can add access, remove access, and get information about
access for a private share group type.
Administrators can specify which `share type(s) <#experimental-apis>`_
a given group type may contain. If Administrators do not explicitly
associate share types with a given share group type, the service will associate
the share type configured as the ``default_share_type`` with the share group
type. When creating a share group, the scheduler picks one of the
back ends that match a combination of the extra specs in the specified share
type(s) and share group type.
Administrators can also set additional group extra specifications for a
share group type for the following purposes:
- Filter back ends by group scheduler. Specify these group extras specifications
in this format: ``group_specs=value``. For example,
``consistent_snapshot_support=true``.
.. note::
Share Group Types APIs are `experimental APIs <#experimental-apis>`_.
List share group types
======================
.. rest_method:: GET /v2/{project_id}/share-group-types
.. versionadded:: 2.31
Lists all share group types.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_group_type_id_required
- is_public: share_group_type_is_public
- share_types: share_types_1
- name: share_group_type_name
- group_specs: group_specs_required
- is_default: is_group_type_default
Response example
----------------
.. literalinclude:: samples/share-group-types-list-response.json
:language: javascript
List default share group types
==============================
.. rest_method:: GET /v2/{project_id}/share-group-types/default
.. versionadded:: 2.31
Lists default share group types.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_group_type_id_required
- is_public: share_group_type_is_public
- share_types: share_types_1
- name: share_group_type_name
- group_specs: group_specs_required
- is_default: is_group_type_default
Response example
----------------
.. literalinclude:: samples/share-group-types-default-list-response.json
:language: javascript
List share group types extra specs
==================================
.. rest_method:: GET /v2/{project_id}/share-group-types/{share_group_type_id}/group_specs
.. versionadded:: 2.31
Lists the extra specifications for a share group type.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_group_type_id: share_group_type_id_required
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_specs: group_specs_required
Response example
----------------
.. literalinclude:: samples/share-group-types-group-specs-list-response.json
:language: javascript
Create share group type
=======================
.. rest_method:: POST /v2/{project_id}/share-group-types
.. versionadded:: 2.31
Creates a share group type.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_types: share_types_1
- name: share_group_type_name_request
- group_specs: group_specs
- is_public: share_group_type_is_public_request
Request example
---------------
.. literalinclude:: samples/share-group-type-create-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_group_type_id_required
- group_specs: group_specs_required
- name: share_group_type_name
- share_types: share_types_1
- is_public: share_group_type_is_public
- is_default: is_group_type_default
Response example
----------------
.. literalinclude:: samples/share-group-type-create-response.json
:language: javascript
Show share group type access details
====================================
.. rest_method:: GET /v2/{project_id}/share-group-types/{share_group_type_id}/share_type_access
.. versionadded:: 2.31
Shows access details for a share group type.
You can view access details for private share group types only.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_group_type_id: share_group_type_id_required
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- share_group_type_id: share_group_type_id_required
- project_id: project_id_type_access
Response example
----------------
.. literalinclude:: samples/share-group-types-list-access-response.json
:language: javascript
Set extra spec for share group type
===================================
.. rest_method:: POST /v2/{project_id}/share-group-types/{share_group_type_id}/group_specs
.. versionadded:: 2.31
Sets an extra specification for the share group type.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_group_type_id: share_group_type_id_required
- group_specs: group_specs_required
Request example
---------------
.. literalinclude:: samples/share-group-type-set-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_specs: group_specs_required
Response example
----------------
.. literalinclude:: samples/share-group-type-set-response.json
:language: javascript
Unset an group spec
===================
.. rest_method:: DELETE /v2/{project_id}/share-group-types/{share_group_type_id}/group-specs/{group_spec_key}
.. versionadded:: 2.31
Unsets an extra specification for the share type.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_group_type_id: share_group_type_id_required
- group_spec_key: group_spec_key
Add share group type access
===========================
.. rest_method:: POST /v2/{project_id}/share-group-types/{share_group_type_id}/action
.. versionadded:: 2.31
Adds share group type access for a project.
You can add access to private share group types only.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_group_type_id: share_group_type_id_path
- addProjectAccess: add_project_access
- project: project_id_type_access_grant_request
Request example
---------------
.. literalinclude:: samples/share-group-type-grant-access-request.json
:language: javascript
Remove share group type access
==============================
.. rest_method:: POST /v2/{project_id}/share-group-types/{share_group_type_id}/action
.. versionadded:: 2.31
Removes share group type access from a project.
You can remove access from private share group types only.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_group_type_id: share_group_type_id_path
- removeProjectAccess: remove_project_access
- project: project_id_type_access_revoke_request
Request example
---------------
.. literalinclude:: samples/share-group-type-revoke-access-request.json
:language: javascript
Delete share group type
=======================
.. rest_method:: DELETE /v2/{project_id}/share-group-types/{share_group_type_id}
.. versionadded:: 2.31
Deletes a share group type.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_group_type_id: share_group_type_id_path