Migrate identity /v2-ext docs from api-ref repo

Docs at [1] have already been converted from WADL (SGML / XML) to RST
using fairy-slipper [2].

This commit polish the results from the conversion and migrate the v2
extension docs to our repository under 'api-ref/source' directory. It
also removes the OS-KSCATALOG, OS-KSS3 and OS-KSVALIDATE docs, given
they do not exist anymore. Missing parameters definitions were added.

The API examples for the extensions were moved into '/v2-ext/samples'.

Polishing the generated RST files include:
- Removing unnecessary blank lines;
- Removing empty references.

Polishing the generated RST files do not include:
- Modifying their content;
- Modifying file names;
- Wrapping lines at the maximum of 79 chars.

Updating the documentation will be done after this migration step.

[1] https://github.com/openstack/api-site/tree/master/api-ref/source/identity/v3
[2] https://github.com/russell/fairy-slipper

Change-Id: If7adf10d0bb5fb07db70d4f42364fa0b50568a01
This commit is contained in:
Samuel de Medeiros Queiroz 2016-05-27 15:44:25 -03:00 committed by Steve Martinelli
parent 3bfb08e4b1
commit 1ee8252e6a
35 changed files with 940 additions and 245 deletions

View File

@ -15,6 +15,9 @@ Contents:
v2/identity-auth.inc
v2/versions.inc
v2-ext/ksadm-admin.inc
v2-ext/ksec2-admin.inc
v3/authenticate-v3.inc
v3/credentials
v3/domains

View File

@ -0,0 +1,646 @@
.. -*- rst -*-
========================
OS-KSADM admin extension
========================
Supports create, read, update, and delete (CRUD) operations for
users, tenants, roles, and services. Requires administrator
privileges.
Grant roles to user on tenant
=============================
.. rest_method:: PUT /v2.0/tenants/{tenantId}/users/{userId}/roles/OS-KSADM/{roleId}
Grants a role to a user for a tenant.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId
- roleId: roleId
- tenantId: tenantId
Revoke role from user on tenant
===============================
.. rest_method:: DELETE /v2.0/tenants/{tenantId}/users/{userId}/roles/OS-KSADM/{roleId}
Revokes a role from a user for a tenant.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId
- roleId: roleId
- tenantId: tenantId
Shows service information by ID
===============================
.. rest_method:: GET /v2.0/services/{serviceId}
Shows information for a service, by ID.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- serviceId: serviceId
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- type: type
- description: description
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/service-show-response.json
:language: javascript
Delete service (admin extension)
================================
.. rest_method:: DELETE /v2.0/services/{serviceId}
Deletes a service.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- serviceId: serviceId
List users on a tenant
======================
.. rest_method:: GET /v2.0/tenants/{tenantId}/users
Lists all users for a tenant.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- tenantId: tenantId
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/users-list-response.json
:language: javascript
Enable user
===========
.. rest_method:: PUT /v2.0/users/{userId}/OS-KSADM/enabled
Enables a user.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId
Request Example
---------------
.. literalinclude:: samples/OS-KSADM/userwithenabledonly-enable-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- enabled: enabled
- email: email
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/user-show-response.json
:language: javascript
List roles (admin extension)
============================
.. rest_method:: GET /v2.0/OS-KSADM/
Lists all roles.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- roles_links: roles_links
- roles: roles
- description: description
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/roles-list-response.json
:language: javascript
List users (admin extension)
============================
.. rest_method:: GET /v2.0/users
Lists all users.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- users: users
- enabled: enabled
- email: email
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/users-list-response.json
:language: javascript
Create user (admin extension)
=============================
.. rest_method:: POST /v2.0/users
Creates a user.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- enabled: enabled
- id: id
- user: user
- users_links: users_links
- email: email
Request Example
---------------
.. literalinclude:: samples/OS-KSADM/userwithoutid-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- enabled: enabled
- email: email
- name: name
- id: id
Show role information by name
=============================
.. rest_method:: GET /v2.0/OS-KSADM/roles/{role_name}
Shows information for a role, by name.
Normal response codes: 200
Error response codes:203,413,415,405,404,403,401,400,503,409,
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Location: Location
- description: description
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/role-show-response.json
:language: javascript
Grant global role to user
=========================
.. rest_method:: PUT /v2.0/users/{userId}/roles/OS-KSADM/{roleId}
Grants a global role to a user.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId
- roleId: roleId
Delete global role from user
============================
.. rest_method:: DELETE /v2.0/users/{userId}/roles/OS-KSADM/{roleId}
Deletes a global role from a user.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId
- roleId: roleId
List services (admin extension)
===============================
.. rest_method:: GET /v2.0/services
Lists all services.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- type: type
- description: description
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/services-list-response.json
:language: javascript
Create service (admin extension)
================================
.. rest_method:: POST /v2.0/services
Creates a service.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request Example
---------------
.. literalinclude:: samples/OS-KSADM/service-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Location: Location
- type: type
- description: description
- name: name
- id: id
Show service information by name
================================
.. rest_method:: GET /v2.0/services/{serviceName}
Shows information for a service, by name.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- type: type
- description: description
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/service-show-response.json
:language: javascript
Create role (admin extension)
=============================
.. rest_method:: POST /v2.0/OS-KSADM
Creates a role.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request Example
---------------
.. literalinclude:: samples/OS-KSADM/role-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Location: Location
Create tenant
=============
.. rest_method:: POST /v2.0/tenants
Creates a tenant.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request Example
---------------
.. literalinclude:: samples/OS-KSADM/tenantwithoutid-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- tenant: tenant
- enabled: enabled
- description: description
- name: name
- id: id
List global roles for user
==========================
.. rest_method:: GET /v2.0/users/{userId}/roles
Lists global roles for a user.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/user-roles-list-response.json
:language: javascript
Update tenant
=============
.. rest_method:: POST /v2.0/tenants/{tenantId}
Updates a tenant.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- tenant: tenant
- enabled: enabled
- description: description
- name: name
- id: id
- tenantId: tenantId
Request Example
---------------
.. literalinclude:: samples/OS-KSADM/tenant-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- tenant: tenant
- enabled: enabled
- description: description
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/tenant-show-response.json
:language: javascript
Delete tenant
=============
.. rest_method:: DELETE /v2.0/tenants/{tenantId}
Deletes a tenant.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- tenantId: tenantId
Show role details, by ID
========================
.. rest_method:: GET /v2.0/OS-KSADM/{roleId}
Shows details for a role, by ID.
Normal response codes: 200
Error response codes:203,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- roleId: roleId
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- Location: Location
- description: description
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/role-show-response.json
:language: javascript
Delete role (admin extension)
=============================
.. rest_method:: DELETE /v2.0/OS-KSADM/{roleId}
Deletes a role.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- roleId: roleId
Update user (admin extension)
=============================
.. rest_method:: PUT /v2.0/users/{userId}
Updates a user.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId
Request Example
---------------
.. literalinclude:: samples/OS-KSADM/user-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- users: users
- enabled: enabled
- email: email
- name: name
- id: id
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/user-show-response.json
:language: javascript
Delete user (admin extension)
=============================
.. rest_method:: DELETE /v2.0/users/{userId}
Deletes a user.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Request
-------
.. rest_parameters:: parameters.yaml
- userId: userId

View File

@ -0,0 +1,114 @@
.. -*- rst -*-
========================
OS-KSEC2 admin extension
========================
Supports Amazon Elastic Compute (EC2) style authentication.
Grant credential to user
========================
.. rest_method:: POST /v2.0/users/{userId}/OS-KSADM/credentials
Grants a credential to a user.
Error response codes:201,413,415,405,404,403,401,400,503,409,
Request Example
---------------
.. literalinclude:: samples/OS-KSEC2/ec2Credentials-create-request.json
:language: javascript
List credentials (EC2 extension)
================================
.. rest_method:: GET /v2.0/users/{userId}/OS-KSADM/credentials
Lists credentials.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Response Example
----------------
.. literalinclude:: samples/OS-KSEC2/credentialswithec2-list-response.json
:language: javascript
Update user credentials
=======================
.. rest_method:: POST /v2.0/users/{userId}/OS-KSADM/credentials/OS-KSEC2:ec2Credentials
Updates credentials for a user.
Normal response codes: 200
Error response codes:413,415,405,404,403,401,400,503,409,
Request Example
---------------
.. literalinclude:: samples/OS-KSEC2/ec2Credentials-create-request.json
:language: javascript
Response Example
----------------
.. literalinclude:: samples/OS-KSEC2/ec2Credentials-show-response.json
:language: javascript
Delete user credentials
=======================
.. rest_method:: DELETE /v2.0/users/{userId}/OS-KSADM/credentials/OS-KSEC2:ec2Credentials
Deletes user credentials.
Error response codes:204,413,415,405,404,403,401,400,503,409,
Get user credentials
====================
.. rest_method:: GET /v2.0/users/{userId}/OS-KSADM/credentials/OS-KSEC2:ec2Credentials
Gets user credentials.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Response Example
----------------
.. literalinclude:: samples/OS-KSEC2/ec2Credentials-show-response.json
:language: javascript
List credentials by type
========================
.. rest_method:: GET /v2.0/users/{userId}/OS-KSADM/credentials/OS-KSEC2:ec2Credentials/{type}
Lists credentials by type.
Normal response codes: 200
Error response codes:203,413,405,404,403,401,400,503,
Request
-------
.. rest_parameters:: parameters.yaml
- type: type
Response Example
----------------
.. literalinclude:: samples/OS-KSADM/credentials-show-response.json
:language: javascript

View File

@ -0,0 +1,177 @@
# variables in header
Location:
format: uri
in: header
required: false
type: string
Location_1:
description: |
The location.
format: uri
in: header
required: false
type: string
# variables in path
roleId:
description: |
The role ID.
in: path
required: false
type: string
serviceId:
description: |
The service ID.
in: path
required: false
type: string
tenantId:
description: |
The tenant ID.
in: path
required: false
type: string
type_1:
description: |
The credential type.
in: path
required: false
type: string
userId:
description: |
The user ID.
in: path
required: false
type: string
# variables in query
# variables in body
description:
description: |
Description about the service.
in: body
required: true
type: string
description_1:
description: |
Description about the tenant.
in: body
required: true
type: string
description_2:
description: |
The role description.
in: body
required: true
type: string
email:
description: |
The user email.
in: body
required: true
type: string
enabled:
description: |
Indicates whether the tenant is enabled or
disabled. Default is ``true``.
in: body
required: true
type: boolean
enabled_1:
description: |
Indicates whether the user is enabled (``true``)
or disabled(``false``). The default value is ``true``.
in: body
required: true
type: boolean
id:
description: |
The UUID of the service.
in: body
required: true
type: string
id_1:
description: |
The tenant ID.
in: body
required: true
type: string
id_2:
description: |
The user ID.
in: body
required: true
type: string
id_3:
description: |
The role ID.
in: body
required: true
type: integer
name:
description: |
The service name.
in: body
required: true
type: string
name_1:
description: |
The tenant name.
in: body
required: true
type: string
name_2:
description: |
The user name.
in: body
required: true
type: string
name_3:
description: |
The role name.
in: body
required: true
type: string
roles:
description: |
A ``roles`` object.
in: body
required: true
type: string
roles_links:
description: |
Role links.
in: body
required: true
type: object
tenant:
description: |
The tenant object.
in: body
required: true
type: string
type:
description: |
The type of the service.
in: body
required: true
type: string
user:
description: |
The ``user`` object.
in: body
required: true
type: string
users:
description: |
The ``users`` object.
in: body
required: true
type: array
users_links:
description: |
The links of ``users`` object.
in: body
required: true
type: array

View File

@ -1,11 +0,0 @@
{
"endpoint": {
"id": 1,
"tenantId": 1,
"region": "North",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
}
}

View File

@ -1,14 +0,0 @@
{
"OS-KSCATALOG:endpointTemplate": {
"id": 1,
"region": "North",
"global": true,
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"versionId": "1",
"versionInfo": "https://compute.north.public.com/v1/",
"versionList": "https://compute.north.public.com/",
"enabled": true
}
}

View File

@ -1,11 +0,0 @@
{
"OS-KSCATALOG:endpointTemplate": {
"id": 1,
"region": "North",
"global": true,
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"enabled": true
}
}

View File

@ -1,5 +0,0 @@
{
"OS-KSCATALOG:endpointTemplate": {
"id": 1
}
}

View File

@ -1,44 +0,0 @@
{
"OS-KSCATALOG:endpointsTemplates": [
{
"id": 1,
"region": "North",
"global": true,
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"enabled": true
},
{
"id": 2,
"region": "South",
"type": "compute",
"publicURL": "https://compute.south.public.com/v1",
"internalURL": "https://compute.south.internal.com/v1",
"enabled": false
},
{
"id": 3,
"region": "North",
"global": true,
"type": "object-store",
"publicURL": "https://object-store.north.public.com/v1.0",
"enabled": true
},
{
"id": 4,
"region": "South",
"type": "object-store",
"publicURL": "https://object-store.south.public.com/v2",
"enabled": true
},
{
"id": 5,
"global": true,
"type": "OS-DNS:DNS",
"publicURL": "https://dns.public.com/v3.2",
"enabled": true
}
],
"OS-KSCATALOG:endpointsTemplates_links": []
}

View File

@ -1,50 +0,0 @@
{
"endpoints": [
{
"id": 1,
"tenantId": "1",
"region": "North",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 2,
"tenantId": "1",
"region": "South",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 3,
"tenantId": "1",
"region": "East",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 4,
"tenantId": "1",
"region": "West",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 5,
"tenantId": "1",
"region": "Global",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
}
],
"endpoints_links": []
}

View File

@ -1,18 +0,0 @@
{
"credentials": [
{
"passwordCredentials": {
"username": "test_user",
"password": "secretsecret"
}
},
{
"OS-KSS3:s3Credentials": {
"username": "test_user",
"secret": "secretsecret",
"signature": "bbb"
}
}
],
"credentials_links": []
}

View File

@ -1,7 +0,0 @@
{
"OS-KSS3:s3Credentials": {
"username": "test_user",
"secret": "secretsecret",
"signature": "bbb"
}
}

View File

@ -1,7 +0,0 @@
{
"OS-KSS3:s3Credentials": {
"username": "test_user",
"secret": "secretsecret",
"signature": "bbb"
}
}

View File

@ -1,50 +0,0 @@
{
"endpoints": [
{
"id": 1,
"tenantId": "1",
"region": "North",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 2,
"tenantId": "1",
"region": "South",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 3,
"tenantId": "1",
"region": "East",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 4,
"tenantId": "1",
"region": "West",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
},
{
"id": 5,
"tenantId": "1",
"region": "Global",
"type": "compute",
"publicURL": "https://compute.north.public.com/v1",
"internalURL": "https://compute.north.internal.com/v1",
"adminURL": "https://compute.north.internal.com/v1"
}
],
"endpoints_links": []
}

View File

@ -1,28 +0,0 @@
{
"access": {
"token": {
"id": "ab48a9efdfedb23ty3494",
"expires": "2010-11-01T03:32:15-05:00",
"tenant": {
"id": "345",
"name": "My Project"
}
},
"user": {
"id": "123",
"name": "jqsmith",
"roles": [
{
"id": "234",
"name": "compute:admin"
},
{
"id": "234",
"name": "object-store:admin",
"tenantId": "1"
}
],
"roles_links": []
}
}
}