openstack/keystone
Code Issues Proposed changes

Clean up the api-ref for groups

Browse Source 
The response paramaters for listing users who are members of a
group will be added in a later patch, once the users api-ref
has been cleaned up.

Change-Id: Ib08ac374f9e16aa443cc33253a84a67ab98958d0
This commit is contained in:
Henry Nash 2016-07-18 03:55:41 +01:00
parent 852bda4eae
commit e4c30cb517
6 changed files with 149 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
api-ref/source/v3/groups.inc
View File

@ -6,22 +6,20 @@
A group is a collection of users. Each group is owned by a domain.
When you grant a role to a group, you explicitly associate that
group with a project or domain. This action is equivalent to
granting the role to each group member on that project and domain.
You can use groups to ease the task of managing role assignments for users.
Assigning a role to a group on a project or domain is equivalent to
assigning the role to each group member on that project or domain.
When you grant a role to a group, that role is automatically granted to any
user within the group. When you revoke a role from a group, that role is
automatically revoked from any user within the group. Any token that
authenticates that user, project, and domain is revoked.
When you unassign a role from a group, that role is automatically unassigned
from any user that is a member of the group. Any tokens that authenticates those
users to the relevant project or domain are revoked.
As with users, a group without any role assignments is useless from the
perspective of an OpenStack service and has no access to resources.
However, a group without role grants is permitted as a way of
However, a group without role assignments is permitted as a way of
acquiring or loading users and groups from external sources before
mapping them to projects and domains.
Show group details
==================
@ -37,7 +35,7 @@ Request
.. rest_parameters:: parameters.yaml
- group_id: group_id
- group_id: group_id_path
Response Parameters
-------------------
@ -45,11 +43,11 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- group: group
- name: name
- links: links
- domain_id: domain_id
- id: id
- description: description
- description: group_description_response_body
- domain_id: group_domain_id_response_body
- id: group_id_response_body
- links: link_response_body
- name: group_name_response_body
Response Example
----------------
@ -76,11 +74,11 @@ Request
.. rest_parameters:: parameters.yaml
- group_id: group_id_path
- group: group
- description: description
- name: name
- domain_id: domain_id
- group_id: group_id
- description: group_description_update_request_body
- domain_id: group_domain_id_update_request_body
- name: group_name_update_request_body
Request Example
---------------
@ -94,11 +92,11 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- group: group
- name: name
- links: links
- domain_id: domain_id
- id: id
- description: description
- description: group_description_response_body
- domain_id: group_domain_id_response_body
- id: group_id_response_body
- links: link_response_body
- name: group_name_response_body
Response Example
----------------
@ -121,7 +119,7 @@ Request
.. rest_parameters:: parameters.yaml
- group_id: group_id
- group_id: group_id_path
Add user to group
@ -138,8 +136,8 @@ Request
.. rest_parameters:: parameters.yaml
- user_id: user_id
- group_id: group_id
- user_id: user_id_path
- group_id: group_id_path
Remove user from group
@ -157,8 +155,8 @@ Request
.. rest_parameters:: parameters.yaml
- user_id: user_id
- group_id: group_id
- user_id: user_id_path
- group_id: group_id_path
Check whether user belongs to group
@ -176,8 +174,8 @@ Request
.. rest_parameters:: parameters.yaml
- user_id: user_id
- group_id: group_id
- user_id: user_id_path
- group_id: group_id_path
List users in group
@ -195,20 +193,7 @@ Request
.. rest_parameters:: parameters.yaml
- group_id: group_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- name: name
- links: links
- enabled: enabled
- domain_id: domain_id
- email: email
- id: id
- users: users
- group_id: group_id_path
Response Example
----------------
@ -233,9 +218,9 @@ Request
.. rest_parameters:: parameters.yaml
- group: group
- description: description
- name: name
- domain_id: domain_id
- description: group_description_request_body
- domain_id: group_domain_id_request_body
- name: group_name_request_body
Request Example
---------------
@ -249,12 +234,17 @@ Response Parameters
.. rest_parameters:: parameters.yaml
- group: group
- name: name
- links: links
- domain_id: domain_id
- id: id
- description: description
- description: group_description_response_body
- domain_id: group_domain_id_response_body
- id: group_id_response_body
- links: link_response_body
- name: group_name_response_body
Response Example
----------------
.. literalinclude:: ./samples/admin/group-show-response.json
:language: javascript
List groups
===========
@ -271,20 +261,21 @@ Request
.. rest_parameters:: parameters.yaml
- name: name
- domain_id: domain_id
- name: group_name_query
- domain_id: domain_id_query
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- name: name
- links: links
- domain_id: domain_id
- links: link_collection
- groups: groups
- id: id
- description: description
- description: group_description_response_body
- domain_id: group_domain_id_response_body
- id: group_id_response_body
- links: link_response_body
- name: group_name_response_body
Response Example
----------------

74
api-ref/source/v3/parameters.yaml
View File

@ -136,7 +136,7 @@ user_id_path:
type: string
# variables in query
domain_id_7:
domain_id_query:
description: |
Filters the response by a domain ID.
in: query
@ -184,6 +184,12 @@ group_id_query:
in: query
required: false
type: string
group_name_query:
description: |
Filters the response by a group name.
in: query
required: false
type: string
include_names_query:
description: |
If set to true, then the names of any entities returned will be include as
@ -709,13 +715,75 @@ extras:
type: object
group:
description: |
A ``group`` object.
A ``group`` object, containing:
in: body
required: true
type: object
group_description_request_body:
description: |
The description of the group.
in: body
required: true
type: string
group_description_response_body:
description: |
The description of the group.
in: body
required: true
type: string
group_description_update_request_body:
description: |
The new description of the group.
in: body
required: false
type: string
group_domain_id_request_body:
description: |
The ID of the domain of the group.
in: body
required: true
type: string
group_domain_id_response_body:
description: |
The ID of the domain of the group.
in: body
required: true
type: string
group_domain_id_update_request_body:
description: |
The ID of the new domain for the group. The ability to change the domain
of a group is now deprecated, and will be removed in subsequent release.
It is already disabled by default in most Identity service implementations.
in: body
required: false
type: string
group_id_response_body:
description: |
The ID of the group.
in: body
required: true
type: string
group_name_request_body:
description: |
The name of the group.
in: body
required: true
type: string
group_name_response_body:
description: |
The name of the group.
in: body
required: true
type: string
group_name_update_request_body:
description: |
The new name of the group.
in: body
required: false
type: string
groups:
description: |
A ``groups`` object.
A list of ``group`` objects, each containing:
in: body
required: true
type: array

2
api-ref/source/v3/samples/admin/group-show-response.json
View File

@ -1,7 +1,7 @@
{
"group": {
"domain_id": "default",
"description": "Contract developers",
"domain_id": "default",
"id": "c0d675eac29945ad9dfd08aa1bb75751",
"links": {
"self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"

2
api-ref/source/v3/samples/admin/group-update-response.json
View File

@ -1,7 +1,7 @@
{
"group": {
"domain_id": "default",
"description": "Contract developers 2016",
"domain_id": "default",
"id": "c0d675eac29945ad9dfd08aa1bb75751",
"links": {
"self": "http://example.com/identity/v3/groups/c0d675eac29945ad9dfd08aa1bb75751"

36
api-ref/source/v3/samples/admin/group-users-list-response.json
View File

@ -1,19 +1,29 @@
{
"users": [
{
"name": "admin",
"links": {
"self": "http://example.com/identity/v3/users/fff603a0829d41e48bc0dd0d72ad61ce"
},
"domain_id": "default",
"enabled": true,
"email": null,
"id": "fff603a0829d41e48bc0dd0d72ad61ce"
}
],
"links": {
"self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92/users",
"previous": null,
"next": null
}
},
"users": [
{
"domain_id": "default",
"description": null,
"enabled": true,
"id": "acd565a08293c1e48bc0dd0d72ad5d5d"
"name": "Henry",
"links": {
"self": "http://example.com/identity/v3/users/acd565a08293c1e48bc0dd0d72ad5d5d"
}
},
{
"domain_id": "default",
"description": null,
"enabled": true,
"id": "fff603a0829d41e48bc0dd0d72ad61ce"
"name": "Paul",
"links": {
"self": "http://example.com/identity/v3/users/fff603a0829d41e48bc0dd0d72ad61ce"
}
}
]
}

4
api-ref/source/v3/samples/admin/groups-list-response.json
View File

@ -6,8 +6,8 @@
},
"groups": [
{
"domain_id": "default",
"description": "non-admin group",
"domain_id": "default",
"id": "96372bbb152f475aa37e9a76a25a029c",
"links": {
"self": "http://example.com/identity/v3/groups/96372bbb152f475aa37e9a76a25a029c"
@ -15,8 +15,8 @@
"name": "nonadmins"
},
{
"domain_id": "default",
"description": "openstack admin group",
"domain_id": "default",
"id": "9ce0ad4e58a84d7a97b92f7955d10c92",
"links": {
"self": "http://example.com/identity/v3/groups/9ce0ad4e58a84d7a97b92f7955d10c92"