api-ref: Document implied roles API

Add documentation for implied roles.

Change-Id: I9fe9123acc8a83379c8dbe02a8fe517add0d8c67
Closes-Bug: #1609164

api-ref/source/v3/parameters.yaml

@@ -66,6 +66,12 @@ group_id_path:
   in: path
   required: true
   type: string
+implies_role_id:
+  description: |
+    Role ID for an implied role.
+  in: path
+  required: true
+  type: string
 option:
   description: |
     The option name. For the ``ldap`` group, a valid
@@ -80,6 +86,12 @@ policy_id_path:
   in: path
   required: true
   type: string
+prior_role_id:
+  description: |
+    Role ID for a prior role.
+  in: path
+  required: true
+  type: string
 project_id_path:
   description: |
     The project ID.
@@ -1008,6 +1020,18 @@ identity:
   in: body
   required: true
   type: object
+implies_role_array_body:
+  description: |
+    An array of implied role objects.
+  in: body
+  required: true
+  type: array
+implies_role_object_body:
+  description: |
+    An implied role object.
+  in: body
+  required: true
+  type: object
 is_domain_request_body:
   description: |
     Indicates whether the project also acts as a domain. If set to ``true``,
@@ -1213,6 +1237,12 @@ policy_user_id_notRequired:
   in: body
   required: false
   type: string
+prior_role_body:
+  description: |
+    A prior role object.
+  in: body
+  required: true
+  type: object
 project:
   description: |
     A ``project`` object, containing:
@@ -1412,6 +1442,19 @@ role_id_response_body:
   in: body
   required: true
   type: string
+role_inference_array_body:
+  description: |
+    An array of ``role_inference`` object.
+  in: body
+  required: true
+  type: array
+role_inference_body:
+  description: |
+    Role inference object that contains ``prior_role`` object
+    and ``implies`` object.
+  in: body
+  required: true
+  type: object
 role_links:
   description: |
     The links for the ``role`` resource.

api-ref/source/v3/roles.inc

@@ -515,6 +515,36 @@ Request
    - user_id: user_id_path
    - role_id: role_id_path
 
+List role assignments for group on domain
+=========================================
+
+.. rest_method::  GET /v3/domains/{domain_id}/groups/{group_id}/roles
+
+Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/domain_group_roles``
+
+Lists role assignments for a group on a domain.
+
+Normal response codes: 200
+Error response codes: 413,405,404,403,401,400,503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - domain_id: domain_id_path
+   - group_id: group_id_path
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/domain-group-roles-list-response.json
+   :language: javascript
+
+The functionality of this request can also be achieved using the generalized
+list assignments API::
+
+  GET /role_assignments?group.id={group_id}&scope.domain.id={domain_id}
 
 List role assignments
 =====================
@@ -655,34 +685,198 @@ Request
 
    - role_id: role_id_path
 
+List implied roles for role
+===========================
 
-List role assignments for group on domain
-=========================================
+.. rest_method:: GET /v3/roles/{prior_role_id}/implies
 
-.. rest_method::  GET /v3/domains/{domain_id}/groups/{group_id}/roles
+Lists implied roles for a role.
 
-Relationship: ``http://docs.openstack.org/api/openstack-identity/3/rel/domain_group_roles``
-
-Lists role assignments for a group on a domain.
+Relationship:
+``http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference``
 
 Normal response codes: 200
-Error response codes: 413,405,404,403,401,400,503
+Error response codes: 401, 404
 
 Request
 -------
 
 .. rest_parameters:: parameters.yaml
 
-   - domain_id: domain_id_path
-   - group_id: group_id_path
+   - prior_role_id: prior_role_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - role_inference: role_inference_body
+   - prior_role: prior_role_body
+   - implies: implies_role_array_body
+   - id: role_id_response_body
+   - links: link_response_body
+   - name: role_name_response_body
 
 Response Example
 ----------------
 
-.. literalinclude:: ./samples/admin/domain-group-roles-list-response.json
+.. literalinclude:: ./samples/admin/list-implied-roles-for-role-response.json
    :language: javascript
 
-The functionality of this request can also be achieved using the generalized
-list assignments API::
+Create role inference rule
+==========================
 
-  GET /role_assignments?group.id={group_id}&scope.domain.id={domain_id}
+.. rest_method:: PUT /v3/roles/{prior_role_id}/implies/{implies_role_id}
+
+Creates a role inference rule.
+
+Relationship:
+``http://developer.openstack.org/api-ref-identity-v3.html#createRoleInference``
+
+Normal response codes: 201
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - prior_role_id: prior_role_id
+   - implies_role_id: implies_role_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - role_inference: role_inference_body
+   - prior_role: prior_role_body
+   - implies: implies_role_object_body
+   - id: role_id_response_body
+   - links: link_response_body
+   - name: role_name_response_body
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/create-role-inferences-response.json
+   :language: javascript
+
+Get role inference rule
+=======================
+
+.. rest_method:: GET /v3/roles/{prior_role_id}/implies/{implies_role_id}
+
+Gets a role inference rule.
+
+Relationship:
+``http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference``
+
+Normal response codes: 200
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - prior_role_id: prior_role_id
+   - implies_role_id: implies_role_id
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - role_inference: role_inference_body
+   - prior_role: prior_role_body
+   - implies: implies_role_object_body
+   - id: role_id_response_body
+   - links: link_response_body
+   - name: role_name_response_body
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/get-role-inferences-response.json
+   :language: javascript
+
+Confirm role inference rule
+===========================
+
+.. rest_method:: HEAD /v3/roles/{prior_role_id}/implies/{implies_role_id}
+
+Checks a role role inference rule.
+
+Relationship:
+``http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference``
+
+Normal response codes: 204
+Error response codes: 401, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - prior_role_id: prior_role_id
+   - implies_role_id: implies_role_id
+
+Response Example
+----------------
+
+Status: 204 No Content
+
+Delete role inference rule
+==========================
+
+.. rest_method:: DELETE /v3/roles/{prior_role_id}/implies/{implies_role_id}
+
+Deletes a role inference rule.
+
+Relationship:
+``http://developer.openstack.org/api-ref-identity-v3.html#deleteRoleInference``
+
+Normal response codes: 204
+Error response codes: 401, 404
+
+.. rest_parameters:: parameters.yaml
+
+   - prior_role_id: prior_role_id
+   - implies_role_id: implies_role_id
+
+Response Example
+----------------
+
+Status: 204 No Content
+
+List all role inference rules
+=============================
+
+.. rest_method:: GET /v3/role_inferences
+
+Lists all role inference rules.
+
+Normal response codes: 200
+Error response codes: 401, 404
+
+Relationship:
+``http://developer.openstack.org/api-ref-identity-v3.html#getRoleInference``
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - role_inferences: role_inference_array_body
+   - prior_role: prior_role_body
+   - implies: implies_role_object_body
+   - id: role_id_response_body
+   - links: link_response_body
+   - name: role_name_response_body
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/admin/role-inferences-response.json
+   :language: javascript

api-ref/source/v3/samples/admin/create-role-inferences-response.json

@@ -0,0 +1,21 @@
+{
+    "role_inference": {
+        "prior_role": {
+            "id": "7ceab6192ea34a548cc71b24f72e762c",
+            "links": {
+                "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c"
+            },
+            "name": "prior role name"
+        },
+        "implies": {
+            "id": "97e2f5d38bc94842bc3da818c16762ed",
+            "links": {
+                "self": "http://example.com/identity/v3/roles/97e2f5d38bc94842bc3da818c16762ed"
+            },
+            "name": "implied role name"
+        }
+    },
+    "links": {
+        "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c/implies/97e2f5d38bc94842bc3da818c16762ed"
+    }
+}

api-ref/source/v3/samples/admin/get-role-inferences-response.json

@@ -0,0 +1,21 @@
+{
+    "role_inference": {
+        "prior_role": {
+            "id": "7ceab6192ea34a548cc71b24f72e762c",
+            "links": {
+                "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c"
+            },
+            "name": "prior role name"
+        },
+        "implies": {
+            "id": "97e2f5d38bc94842bc3da818c16762ed",
+            "links": {
+                "self": "http://example.com/identity/v3/roles/97e2f5d38bc94842bc3da818c16762ed"
+            },
+            "name": "implied role name"
+        }
+    },
+    "links": {
+        "self": "http://example.com/identity/v3/roles/7ceab6192ea34a548cc71b24f72e762c/implies/97e2f5d38bc94842bc3da818c16762ed"
+    }
+}

api-ref/source/v3/samples/admin/list-implied-roles-for-role-response.json

@@ -0,0 +1,30 @@
+{
+    "role_inference": {
+        "prior_role": {
+            "id": "42c764f0c19146728dbfe73a49cc35c3",
+            "links": {
+                "self": "http://example.com/identity/v3/roles/42c764f0c19146728dbfe73a49cc35c3"
+            },
+            "name": "prior role name"
+        },
+        "implies": [
+            {
+                "id": "066fbfc8b3e54fb68784c9e7e92ab8d7",
+                "links": {
+                    "self": "http://example.com/identity/v3/roles/066fbfc8b3e54fb68784c9e7e92ab8d7"
+                },
+                "name": "implied role1 name"
+            },
+            {
+                "id": "32a0df1cc22848aca3986adae9e0b9a0",
+                "links": {
+                    "self": "http://example.com/identity/v3/roles/32a0df1cc22848aca3986adae9e0b9a0"
+                },
+                "name": "implied role2 name"
+            }
+        ]
+    },
+    "links" : {
+        "self": "http://example.com/identity/v3/roles/42c764f0c19146728dbfe73a49cc35c3/implies"
+    }
+}

api-ref/source/v3/samples/admin/role-inferences-response.json

@@ -0,0 +1,57 @@
+{
+    "role_inferences": [
+        {
+            "prior_role": {
+                "id": "1acd3c5aa0e246b9a7427d252160dcd1",
+                "links": {
+                    "self": "http://example.com/identity/v3/roles/1acd3c5aa0e246b9a7427d252160dcd1"
+                },
+                "name": "prior role name"
+            },
+            "implies": [
+                {
+                    "id": "3602510e2e1f499589f78a0724dcf614",
+                    "links": {
+                        "self": "http://example.com/identity/v3/roles/3602510e2e1f499589f78a0724dcf614"
+                    },
+                    "name": "implied role1 name"
+                },
+                {
+                    "id": "738289aeef684e73a987f7cf2ec6d925",
+                    "links": {
+                        "self": "http://example.com/identity/v3/roles/738289aeef684e73a987f7cf2ec6d925"
+                    },
+                    "name": "implied role2 name"
+                }
+            ]
+        },
+        {
+            "prior_role": {
+                "id": "bbf7a5098bb34407b7164eb6ff9f144e",
+                "links": {
+                    "self" : "http://example.com/identity/v3/roles/bbf7a5098bb34407b7164eb6ff9f144e"
+                },
+                "name": "prior role name"
+            },
+            "implies": [
+                {
+                    "id": "872b20ad124c4c1bafaef2b1aae316ab",
+                    "links": {
+                        "self": "http://example.com/identity/v3/roles/872b20ad124c4c1bafaef2b1aae316ab"
+                    },
+                    "name": "implied role1 name"
+                },
+                {
+                    "id": "1d865b1b2da14cb7b05254677e5f36a2",
+                    "links": {
+                        "self": "http://example.com/identity/v3/roles/1d865b1b2da14cb7b05254677e5f36a2"
+                    },
+                    "name": "implied role2 name"
+                }
+            ]
+        }
+    ],
+    "links": {
+        "self": "http://example.com/identity/v3/role_inferences"
+    }
+}