x/valet
Code Issues Proposed changes
master
valet/api-ref/source/v1/groups.inc
Tin Lam 0192a4ab0c Add api-ref to valet 
This patch set is one of many to add api reference documentation to valet.
This specifc patch adds the /v1/groups/ api documentation.  User
can generate the documentation by ``tox -eapi-ref``.

Change-Id: Ic5016abd9f95de98effeaceb4b9f8c1fc7943d6a
Signed-off-by: Tin Lam <tin@irrational.io>
2017-05-30 13:36:49 -05:00

344 lines
5.2 KiB
ReStructuredText
Raw Permalink Blame History

.. -*- rst -*-
======
Groups
======
Create a group
==============
.. rest_method:: POST /v1/groups
Creates a group.
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 201
.. rest_status_code:: error ../status.yaml
- 400
- 401
- 500
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- name: group_name
- description: group_description
- type: group_type
Request Example
---------------
.. literalinclude:: ./samples/create_group_request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: group_description
- id: group_id_body
- members: group_members
- name: group_name
- type: group_type
Response Parameters
-------------------
.. literalinclude:: ./samples/create_group_response.json
:language: json
List groups
===========
.. rest_method:: GET /v1/groups
Lists groups.
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 401
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: group_description
- id: group_id_body
- members: group_members
- name: group_name
- type: group_type
Response Example
----------------
.. literalinclude:: ./samples/list_groups_response.json
:language: json
Show group
==========
.. rest_method:: GET /v1/groups/{group_id}
Lists groups.
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 401
- 404
Request Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_id: group_id_query
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: group_description
- id: group_id_body
- members: group_members
- name: group_name
- type: group_type
Response Example
----------------
.. literalinclude:: ./samples/show_group_response.json
:language: json
Update a group
==============
.. rest_method:: PUT /v1/groups/{group_id}
Updates a group.
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 201
.. rest_status_code:: error ../status.yaml
- 400
- 401
- 404
Request Parameters
------------------
.. rest_parameters:: parameters.yaml
- group_id: group_id_query
- description: group_description
Response Example
----------------
.. literalinclude:: ./samples/update_group_request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: group_description
- id: group_id_body
- members: group_members
- name: group_name
- type: group_type
Response Example
----------------
.. literalinclude:: ./samples/update_group_response.json
:language: json
Delete group
============
.. rest_method:: DELETE /v1/groups/{group_id}
Lists groups.
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 204
.. rest_status_code:: error ../status.yaml
- 400
- 401
- 404
- 409
Request Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_id: group_id_query
Add members to group
====================
.. rest_method:: PUT /v1/groups/{group_id}/members
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 201
.. rest_status_code:: error ../status.yaml
- 400
- 401
- 404
- 409
Request Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_id: group_id_query
- members: group_members
Response Example
----------------
.. literalinclude:: ./samples/add_members_request.json
:language: json
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- description: group_description
- id: group_id_body
- members: group_members
- name: group_name
- type: group_type
Response Example
----------------
.. literalinclude:: ./samples/add_members_response.json
:language: json
Verify membership in a group
============================
.. rest_method:: GET /v1/groups/{group_id}/members/{member_id}
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 400
- 401
- 404
Request Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_id: group_id_query
- member_id: member_id_query
Delete all members from a group
===============================
.. rest_method:: DELETE /v1/groups/{group_id}/members
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 204
.. rest_status_code:: error ../status.yaml
- 400
- 401
- 404
Request Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_id: group_id_query
Delete a member from group
==========================
.. rest_method:: DELETE /v1/groups/{group_id}/members/{member_id}
Response Codes
--------------
.. rest_status_code:: success ../status.yaml
- 204
.. rest_status_code:: error ../status.yaml
- 400
- 401
- 404
Request Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_id: group_id_query
- member_id: member_id_query
View Git Blame Copy Permalink