Migrate identity /v3-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 v3
extension docs to our repository under 'api-ref/source' directory. It
also removes the OS-KDS docs, given it does not exist anymore. Missing
parameters definitions were added.

The API examples for the extensions were moved into '/v3-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: I632ac0aaa8e1ba2eeb598f5fd80350ac0c5ad3c1

api-ref/source/index.inc

@@ -24,6 +24,10 @@ Contents:
    v3/service-catalog
    v3/users
 
+   v3-ext/identity_v3_OS-ENDPOINT-POLICY-ext.inc
+   v3-ext/inherit.inc
+   v3-ext/trust.inc
+
 
 Indices and tables
 ==================

api-ref/source/v3-ext/identity_v3_OS-ENDPOINT-POLICY-ext.inc

@@ -0,0 +1,308 @@
+.. -*- rst -*-
+
+=================================================
+OS-ENDPOINT-POLICY extension (OS-ENDPOINT-POLICY)
+=================================================
+
+Creates, verifies, and deletes associations between service
+endpoints and policies. Such associations enable an endpoint to
+request its policy.
+
+To create, check, or delete an association, you reference a policy
+by its ID in the Identity server.
+
+The extension supports these associations:
+
+- A policy and endpoint association.
+
+- A policy and service-type endpoint in a region association.
+
+- A policy and service-type endpoint association.
+
+This order reflects policies in their most to least-specific order.
+
+When an endpoint requests the appropriate policy for itself, the
+extension finds the policy by traversing the ordered sequence of
+methods of association. The extension shows the policy for the
+first association that it finds.
+
+If the region of the endpoint has a parent, the extension examines
+the region associations up the region tree in ascending order. For
+region associations, the extension examines any parent regions in
+ascending order. The extension does not combine polices.
+
+
+Associate policy and service-type endpoint
+==========================================
+
+.. rest_method::  PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}
+
+Associates a policy and any endpoint of a service type.
+
+If an association already exists between the endpoint of a service
+type and another policy, this call replaces that association.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - service_id: service_id
+   - policy_id: policy_id
+
+
+Verify a policy and service-type endpoint association
+=====================================================
+
+.. rest_method::  GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}
+
+Verifies an association between a policy and an endpoint of a service type.
+
+A HEAD version of this API is also supported.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - service_id: service_id
+   - policy_id: policy_id
+
+
+Delete a policy and service-type endpoint association
+=====================================================
+
+.. rest_method::  DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/{service_id}
+
+Deletes an association between a policy and an endpoint of a service type.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - service_id: service_id
+   - policy_id: policy_id
+
+
+Show policy for endpoint
+========================
+
+.. rest_method::  GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/policy
+
+Shows a policy for an endpoint.
+
+The extension finds the policy by traversing the ordered sequence
+of methods of association. The extension shows the policy for the
+first association that it finds. If the region of the endpoint has
+a parent, the extension examines the region associations up the
+region tree in ascending order.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: policy_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy: policy
+   - type: type
+   - blob: blob
+   - links: links
+   - id: id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-ENDPOINT-POLICY/policy-show-response.json
+   :language: javascript
+
+
+Check policy and service endpoint association
+=============================================
+
+.. rest_method::  HEAD /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/policy
+
+Checks whether a policy is associated with an endpoint.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: policy_id
+
+
+Associate policy and service-type endpoint in a region
+======================================================
+
+.. rest_method::  PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/regions/{region_id}
+
+Associates a policy and an endpoint of a service type in a region.
+
+If an association already exists between the service in a region
+and another policy, this call replaces that association.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - region_id: region_id
+   - policy_id: policy_id
+
+
+Verify a policy and service-type endpoint in a region association
+=================================================================
+
+.. rest_method::  GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/regions/{region_id}
+
+Verifies an association between a policy and service-type endpoint in a region.
+
+A HEAD version of this API is also supported.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - region_id: region_id
+   - policy_id: policy_id
+
+
+Delete a policy and service-type endpoint in a region association
+=================================================================
+
+.. rest_method::  DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/services/regions/{region_id}
+
+Deletes an association between a policy and service-type endpoint in a region.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - region_id: region_id
+   - policy_id: policy_id
+
+
+List policy and service endpoint associations
+=============================================
+
+.. rest_method::  GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints
+
+Lists all the endpoints that are currently associated with a policy through any of the association methods.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - policy_id: policy_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - links: links
+   - url: url
+   - region: region
+   - next: next
+   - self: self
+   - interface: interface
+   - service_id: service_id
+   - endpoints: endpoints
+   - id: id
+   - previous: previous
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-ENDPOINT-POLICY/policy-endpoint-associations-list-response.json
+   :language: javascript
+
+
+Associate policy and endpoint
+=============================
+
+.. rest_method::  PUT /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}
+
+Associates a policy and an endpoint.
+
+If an association already exists between the endpoint and another
+policy, this call replaces that association.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoint_id: endpoint_id
+   - policy_id: policy_id
+
+
+Verify a policy and endpoint association
+========================================
+
+.. rest_method::  GET /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}
+
+Verifies an association between a policy and an endpoint.
+
+A HEAD version of this API is also supported.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoint_id: endpoint_id
+   - policy_id: policy_id
+
+
+Delete a policy and endpoint association
+========================================
+
+.. rest_method::  DELETE /v3/policies/{policy_id}/OS-ENDPOINT-POLICY/endpoints/{endpoint_id}
+
+Deletes an association between a policy and an endpoint.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - endpoint_id: endpoint_id
+   - policy_id: policy_id

api-ref/source/v3-ext/inherit.inc

@@ -0,0 +1,441 @@
+.. -*- rst -*-
+
+=================================
+OS-INHERIT extension (OS-INHERIT)
+=================================
+
+Enables projects to inherit role assignments from either their
+owning domain or projects that are higher in the hierarchy.
+
+(Since API v3.4) The OS-INHERIT extension allows inheritance from
+both projects and domains. To access project inheritance, the
+Identity service server must run at least API v3.4.
+
+
+Assign role to user owned by domain projects
+============================================
+
+.. rest_method::  PUT /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+
+Assigns a role to a user in projects owned by a domain.
+
+The API applies the inherited role to the existing and future owned
+projects. The inherited role does not appear as a role in a domain-
+scoped token.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - role_id: role_id
+   - domain_id: domain_id
+
+
+Check project role for user in domain
+=====================================
+
+.. rest_method::  HEAD /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+
+Checks whether a user has an inherited project role in a domain.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - role_id: role_id
+   - domain_id: domain_id
+
+
+Revoke project role from user in domain
+=======================================
+
+.. rest_method::  DELETE /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+
+Revokes an inherited project role from a user in a domain.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - role_id: role_id
+   - domain_id: domain_id
+
+
+Assign role to group
+====================
+
+.. rest_method::  PUT /v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+
+Assigns a role to a group in projects in a subtree.
+
+The API anchors the inherited role assignment to a project and
+applies it to its subtree in the projects hierarchy to both
+existing and future projects.
+
+A group can have both a regular, non-inherited role assignment and
+an inherited role assignment in the same project.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - role_id: role_id
+   - project_id: project_id
+
+
+Check role for group
+====================
+
+.. rest_method::  HEAD /v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+
+Checks whether a group has a role assignment with the ``inherited_to_projects`` flag in a project.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - role_id: role_id
+   - project_id: project_id
+
+
+Revoke role from group
+======================
+
+.. rest_method::  DELETE /v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+
+Revokes an inherited role from a group in a project.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - role_id: role_id
+   - project_id: project_id
+
+
+Assign role to group in domain projects
+=======================================
+
+.. rest_method::  PUT /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+
+Assigns a role to a group in projects owned by a domain.
+
+The API applies the inherited role to owned projects, both existing
+and future. The inherited role does not appear as a role in a
+domain-scoped token.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - role_id: role_id
+   - domain_id: domain_id
+
+
+Check project role for group in domain
+======================================
+
+.. rest_method::  HEAD /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+
+Checks whether a group has an inherited project role in a domain.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - role_id: role_id
+   - domain_id: domain_id
+
+
+Revoke project role from group in domain
+========================================
+
+.. rest_method::  DELETE /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/{role_id}/inherited_to_projects
+
+Revokes an inherited project role from a group in a domain.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - role_id: role_id
+   - domain_id: domain_id
+
+
+Assign role to user
+===================
+
+.. rest_method::  PUT /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+
+Assigns a role to a user in projects in a subtree.
+
+The API anchors the inherited role assignment to a project and
+applies it to its subtree in the projects hierarchy to both
+existing and future projects.
+
+A user can have both a regular, non-inherited role assignment and
+an inherited role assignment in the same project.
+
+Error response codes:204,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - role_id: role_id
+   - project_id: project_id
+
+
+Check role for user
+===================
+
+.. rest_method::  HEAD /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+
+Checks whether a user has a role assignment with the ``inherited_to_projects`` flag in a project.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - role_id: role_id
+   - project_id: project_id
+
+
+Revoke role from user
+=====================
+
+.. rest_method::  DELETE /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/{role_id}/inherited_to_projects
+
+Revokes an inherited role from a user in a project.
+
+Error response codes:204
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - role_id: role_id
+   - project_id: project_id
+
+
+List project roles for group in domain
+======================================
+
+.. rest_method::  GET /v3/OS-INHERIT/domains/{domain_id}/groups/{group_id}/roles/inherited_to_projects
+
+Lists the project roles that a group inherits from a parent project in a domain.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - domain_id: domain_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-INHERIT/group-roles-domain-list-response.json
+   :language: javascript
+
+
+List effective role assignments
+===============================
+
+.. rest_method::  GET /v3/role_assignments
+
+Lists role assignments.
+
+The scope section in the list response is extended to allow the
+representation of role assignments that are inherited to projects.
+
+The list of all role assignments can be long. To filter the list,
+use the query parameters.
+
+Some typical examples are:
+
+``GET /role_assignments?user.id={user_id}`` lists all role
+assignments for a user.
+
+``GET /role_assignments?scope.project.id={project_id}`` lists all
+role assignments for a project.
+
+Each role assignment entity in the collection contains a link to
+the assignment that created this entity.
+
+Use the ``effective`` query parameter to list effective assignments
+at the user, project, and domain level. This parameter allows for
+the effects of group membership as well as inheritance from the
+parent domain or project, for role assignments that were made using
+OS-INHERIT assignment APIs.
+
+The group role assignment entities themselves are not returned in
+the collection. Because, like group membership, the effects of
+inheritance have already been allowed for, the role assignment
+entities themselves that specify the inheritance are not returned
+in the collection. This represents the effective role assignments
+that would be included in a scoped token. You can use the other
+query parameters with the ``effective`` parameter.
+
+For example, to determine what a user can actually do, issue this
+request: ``GET /role_assignments?user.id={user_id} & effective``
+
+To get the equivalent set of role assignments that would be
+included in the token response of a project-scoped token, issue
+``GET /role_assignments?user.id={user_id} &
+scope.project.id={project_id} & effective``
+
+In the response, the entity ``links`` section for entities that are
+included by virtue of group members also contains a url that you
+can use to access the membership of the group.
+
+Use the ``scope.OS-INHERIT:inherited_to`` query parameter to filter
+the response by inherited role assignments. The ``scope.OS-
+INHERIT:inherited_to`` value of ``projects`` is currently
+supported. This value indicates that this role is inherited to all
+projects of the owning domain or parent project.
+
+An example response for an API call with the ``effective`` query
+string:
+
+Normal response codes: 200
+Error response codes:413,405,404,403,401,400,503,
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-INHERIT/role-assignments-effective-list-response.json
+   :language: javascript
+
+
+List project roles for user in domain
+=====================================
+
+.. rest_method::  GET /v3/OS-INHERIT/domains/{domain_id}/users/{user_id}/roles/inherited_to_projects
+
+Lists the project roles that a user inherits from a parent project in a domain.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - domain_id: domain_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-INHERIT/user-roles-domain-list-response.json
+   :language: javascript
+
+
+List roles for group
+====================
+
+.. rest_method::  GET /v3/OS-INHERIT/projects/{project_id}/groups/{group_id}/roles/inherited_to_projects
+
+Lists the project roles that a group in a project inherits from a parent project.
+
+The list shows only roles that the group project inherits from the
+parent project.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - group_id: group_id
+   - project_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-INHERIT/group-roles-list-response.json
+   :language: javascript
+
+
+List roles for user
+===================
+
+.. rest_method::  GET /v3/OS-INHERIT/projects/{project_id}/users/{user_id}/roles/inherited_to_projects
+
+Lists the project roles that a user in a project inherits from a parent project.
+
+The list shows only roles that the user project inherits from the
+parent project.
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - user_id: user_id
+   - project_id: project_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/OS-INHERIT/user-roles-list-response.json
+   :language: javascript

api-ref/source/v3-ext/parameters.yaml

@@ -0,0 +1,280 @@
+# variables in header
+
+# variables in path
+access_token_id:
+  description: |
+    The UUID of the access token.
+  in: path
+  required: false
+  type: string
+consumer_id:
+  description: |
+    The UUID of the consumer.
+  in: path
+  required: false
+  type: string
+domain_id:
+  description: |
+    The UUID of the domain.
+  in: path
+  required: false
+  type: string
+endpoint_id:
+  description: |
+    The endpoint ID.
+  in: path
+  required: false
+  type: string
+group_id:
+  description: |
+    The UUID of the group.
+  in: path
+  required: false
+  type: string
+name:
+  description: |
+    The name of the group.
+  in: path
+  required: false
+  type: string
+policy_id:
+  description: |
+    The policy ID.
+  in: path
+  required: false
+  type: string
+project_id:
+  description: |
+    The UUID of the project.
+  in: path
+  required: false
+  type: string
+region_id:
+  description: |
+    The region ID.
+  in: path
+  required: false
+  type: string
+role_id:
+  description: |
+    The UUID of the role.
+  in: path
+  required: false
+  type: string
+service_id:
+  description: |
+    The service ID.
+  in: path
+  required: false
+  type: string
+user_id:
+  description: |
+    The UUID of the user.
+  in: path
+  required: false
+  type: string
+
+# variables in query
+
+# variables in body
+blob:
+  description: |
+    The policy rule itself, as a serialized blob.
+  in: body
+  required: true
+  type: object
+endpoints:
+  description: |
+    An ``endpoints`` object.
+  in: body
+  required: true
+  type: array
+id:
+  description: |
+    The ID of the trust.
+  in: body
+  required: true
+  type: string
+id_1:
+  description: |
+    The endpoint UUID.
+  in: body
+  required: true
+  type: string
+id_2:
+  description: |
+    The ID of the policy.
+  in: body
+  required: true
+  type: string
+impersonation:
+  description: |
+    The impersonation flag. Default is false.
+  in: body
+  required: false
+  type: boolean
+interface:
+  description: |
+    The interface type, which describes the
+    visibility of the endpoint.  Value is:  - ``public``. Visible by
+    end users on a publicly available network   interface.  -
+    ``internal``. Visible by end users on an unmetered internal
+    network interface.  - ``admin``. Visible by administrative users
+    on a secure network   interface.
+  in: body
+  required: true
+  type: string
+links:
+  description: |
+    Trust links.
+  in: body
+  required: true
+  type: object
+links_1:
+  description: |
+    The links for the ``endpoints`` resource.
+  in: body
+  required: true
+  type: object
+links_2:
+  description: |
+    The links for the ``policy`` resource.
+  in: body
+  required: true
+  type: object
+name_1:
+  description: |
+    The role name.
+  in: body
+  required: true
+  type: string
+name_2:
+  description: |
+    The name of the group.
+  in: body
+  required: true
+  type: string
+next:
+  description: |
+    The ``next`` relative link for the ``endpoints``
+    resource.
+  in: body
+  required: true
+  type: string
+oauth_expires_at:
+  description: |
+    The date and time when a request token expires.
+
+    The date and time stamp format is `ISO 8601
+    <https://en.wikipedia.org/wiki/ISO_8601>`_:
+
+    ::
+
+       CCYY-MM-DDThh:mm:ss±hh:mm
+
+    The ``±hh:mm`` value, if included, is the time zone as an offset
+    from UTC.
+
+    For example, ``2015-08-27T09:49:58-05:00``.
+
+    If the Identity API does not include this attribute or its value is
+    ``null``, the token never expires.
+  in: body
+  required: false
+  type: string
+policy:
+  description: |
+    A ``policy`` object.
+  in: body
+  required: true
+  type: object
+previous:
+  description: |
+    The ``previous`` relative link for the
+    ``endpoints`` resource.
+  in: body
+  required: true
+  type: string
+project_id_1:
+  description: |
+    The ID of the project.
+  in: body
+  required: true
+  type: string
+region:
+  description: |
+    (Deprecated in v3.2) The geographic location of
+    the service endpoint.
+  in: body
+  required: true
+  type: string
+remaining_uses:
+  description: |
+    Remaining uses flag. Default is null.
+  in: body
+  required: false
+  type: boolean
+roles:
+  description: |
+    A roles object.
+  in: body
+  required: true
+  type: array
+roles_links:
+  description: |
+    A roles links object. Includes ``next``,
+    ``previous``, and ``self`` links for roles.
+  in: body
+  required: true
+  type: object
+self:
+  description: |
+    The ``self`` relative link for the ``endpoints``
+    resource.
+  in: body
+  required: true
+  type: string
+service_id_1:
+  description: |
+    The UUID of the service to which the endpoint
+    belongs.
+  in: body
+  required: true
+  type: string
+trust:
+  description: |
+    A trust object.
+  in: body
+  required: true
+  type: object
+trustee_user_id:
+  description: |
+    The trustee user ID.
+  in: body
+  required: true
+  type: string
+trustor_user_id:
+  description: |
+    The trustor user ID.
+  in: body
+  required: true
+  type: string
+type:
+  description: |
+    The MIME media type of the serialized policy
+    blob. From the perspective of the Identity API, a policy blob can
+    be based on any technology. In OpenStack, the ``policy.json`` blob
+    (``type="application/json"``) is the conventional solution.
+    However, you might want to use an alternative policy engine that
+    uses a different policy language type. For example,
+    ``type="application/xacml+xml"``.
+  in: body
+  required: true
+  type: string
+url:
+  description: |
+    The endpoint URL.
+  in: body
+  required: true
+  type: string
+

api-ref/source/v3-ext/trust.inc

@@ -0,0 +1,71 @@
+.. -*- rst -*-
+
+==========================
+Trust extension (OS-TRUST)
+==========================
+
+Creates a trust.
+
+A trust is an OpenStack Identity extension that enables delegation
+and, optionally, impersonation through ``keystone``. A trust
+extension defines a relationship between a trustor and trustee. A
+trustor is the user who delegates a limited set of their own rights
+to another user, known as the trustee, for a limited time.
+
+The trust can eventually enable the trustee to impersonate the
+trustor. For security reasons, some safety measures are added. For
+example, if a trustor loses a given role, the API automatically
+revokes any trusts and the related tokens that the user issued with
+that role.
+
+For more information, see `Use trusts <http://docs.openstack.org
+/admin-guide/keystone_use_trusts.html>`_.
+
+
+Create trust
+============
+
+.. rest_method::  POST /v3/OS-TRUST/trusts
+
+Creates a trust.
+
+Error response codes:201,413,415,405,404,403,401,400,503,409,
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - impersonation: impersonation
+   - trust: trust
+   - trustor_user_id: trustor_user_id
+   - name: name
+   - roles: roles
+   - oauth_expires_at: oauth_expires_at
+   - remaining_uses: remaining_uses
+   - trustee_user_id: trustee_user_id
+   - project_id: project_id
+
+Request Example
+---------------
+
+.. literalinclude:: samples/OS-TRUST/trust-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - impersonation: impersonation
+   - roles_links: roles_links
+   - trust: trust
+   - trustor_user_id: trustor_user_id
+   - name: name
+   - links: links
+   - oauth_expires_at: oauth_expires_at
+   - remaining_uses: remaining_uses
+   - trustee_user_id: trustee_user_id
+   - roles: roles
+   - project_id: project_id
+   - id: id

api-ref/source/v3/samples/OS-KDS/group-create-request.json

@@ -1,3 +0,0 @@
-{
-    "key": "TXkgcHJlY2lvdXNzcy4u..."
-}

api-ref/source/v3/samples/OS-KDS/group-create-response.json

@@ -1,3 +0,0 @@
-{
-    "name": "--group-name--"
-}

api-ref/source/v3/samples/OS-KDS/group-key-show-response.json

@@ -1,3 +0,0 @@
-{
-    "name": "--group-name--"
-}

api-ref/source/v3/samples/OS-KDS/key-create-request.json

@@ -1,3 +0,0 @@
-{
-    "key": "TXkgcHJlY2lvdXNzcy4u..."
-}

api-ref/source/v3/samples/OS-KDS/key-create-response.json

@@ -1,4 +0,0 @@
-{
-    "name": "TXkgcHJlY2lvdXNzcy4u...",
-    "generation": 2
-}

api-ref/source/v3/samples/OS-KDS/ticket-generate-request.json

@@ -1,4 +0,0 @@
-{
-    "metadata": "Zhn8yhasf8hihkf...",
-    "signature": "c2lnbmF0dXJl..."
-}

api-ref/source/v3/samples/OS-KDS/ticket-generate-response.json

@@ -1,6 +0,0 @@
-{
-    "source": "scheduler.host.example.com",
-    "destination": "compute.host.example.com",
-    "timestamp": "2012-03-26T10:01:01.720000",
-    "nonce": 1234567890
-}