From 1121ccfb8309cfe69ea3a7f595f5a6a6960aad82 Mon Sep 17 00:00:00 2001 From: Suramya Shah Date: Mon, 8 Jan 2018 19:33:24 +0530 Subject: [PATCH] Reorganize api-ref: v3-ext trust.inc Reorganize as per the documentation session at PTG: https://etherpad.openstack.org/p/queens-ptg-keystone-doc-cleanup Closes-Bug: 1747694 Change-Id: I951eaae91bf52c6a56ffd27116ac3d07e76ebf13 --- api-ref/source/v3-ext/parameters.yaml | 19 +- api-ref/source/v3-ext/trust.inc | 273 ++++++++++++------ .../notes/bug-1747694-48c8caa4871300e3.yaml | 7 + 3 files changed, 214 insertions(+), 85 deletions(-) create mode 100644 releasenotes/notes/bug-1747694-48c8caa4871300e3.yaml diff --git a/api-ref/source/v3-ext/parameters.yaml b/api-ref/source/v3-ext/parameters.yaml index 9418b53be2..2d2fab1c21 100644 --- a/api-ref/source/v3-ext/parameters.yaml +++ b/api-ref/source/v3-ext/parameters.yaml @@ -93,7 +93,6 @@ user_id_path: type: string # variables in query - since_query: description: | A timestamp used to limit the list of results to events @@ -103,6 +102,24 @@ since_query: required: false type: string +trustee_user_id_query: + description: | + Filters the response by a trustee user ID. + In order to list trusts for a given trustee, filter the collection using a query string + (e.g., ``?trustee_user_id={user_id}``). + in: query + required: false + type: string + +trustor_user_id_query: + description: | + Filters the response by a trustor user ID. + In order to list trusts for a given trustor, filter the collection using a query string + (e.g., ``?trustor_user_id={user_id}``). + in: query + required: false + type: string + # variables in body allow_redelegation: description: | diff --git a/api-ref/source/v3-ext/trust.inc b/api-ref/source/v3-ext/trust.inc index c5cfdc8cc4..07fdb205ee 100644 --- a/api-ref/source/v3-ext/trust.inc +++ b/api-ref/source/v3-ext/trust.inc @@ -63,8 +63,11 @@ If the trust has the ``impersonation`` attribute set to `true`, then the resulti token’s user attribute will also represent the trustor, rather than the authenticating user (the trustee). -Request Example ----------------- +Request +------- + +Example +~~~~~~~ .. literalinclude:: samples/OS-TRUST/trust-auth-request.json :language: javascript @@ -73,8 +76,11 @@ A token created from a trust will have an ``OS-TRUST:trust`` section containing ``id`` of the trust, the ``impersonation`` flag, the ``trustee_user_id`` and the ``trustor_user_id``. -Response Example ----------------- +Response +-------- + +Example +~~~~~~~ .. literalinclude:: samples/OS-TRUST/trust-auth-trust-response.json :language: javascript @@ -83,9 +89,6 @@ A token created from a redelegated trust will have an ``OS-TRUST:trust`` section containing the same fields as a regular trust token, only ``redelegated_trust_id`` and ``redelegation_count`` are added. -Response Example ----------------- - .. literalinclude:: samples/OS-TRUST/trust-auth-redelegated-response.json :language: javascript @@ -95,19 +98,16 @@ Create trust .. rest_method:: POST /v3/OS-TRUST/trusts -Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts`` - Creates a trust. -Relationship: https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts - -Normal response codes: 201 - -Error response codes: 413, 415, 405, 404, 403, 401, 400, 503, 409 +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts`` Request ------- +Parameters +~~~~~~~~~~ + .. rest_parameters:: parameters.yaml - trust: trust @@ -122,16 +122,19 @@ Request - remaining_uses: remaining_uses - roles: trust_roles -Request Example ---------------- +Example +~~~~~~~ Status: 201 Created .. literalinclude:: samples/OS-TRUST/trust-create-request.json :language: javascript -Response Parameters -------------------- +Response +-------- + +Parameters +~~~~~~~~~~ .. rest_parameters:: parameters.yaml @@ -150,8 +153,27 @@ Response Parameters - roles_links: roles_links - links: trust_links -Response Example ----------------- +Status Codes +~~~~~~~~~~~~ + +.. rest_status_code:: success ../v3/status.yaml + + - 201 + +.. rest_status_code:: error ../v3/status.yaml + + - 400 + - 401 + - 403 + - 404 + - 405 + - 409 + - 413 + - 415 + - 503 + +Example +~~~~~~~ Status: 201 Created @@ -163,37 +185,26 @@ List trusts .. rest_method:: GET /v3/OS-TRUST/trusts -Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts`` - Lists all trusts. -Normal response codes: 200 +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trusts`` -Error response codes: 400, 401, 403, 404, 405, 413, 503 +Request +------- -The following optional query strings are supported: +Parameters +~~~~~~~~~~ -- ``page`` -- ``per_page`` (default 30) -- ``trustor_user_id`` -- ``trustee_user_id`` +.. rest_parameters:: parameters.yaml -In order to list trusts for a given trustor, filter the collection using a query string -(e.g., ``?trustor_user_id={user_id}``). + - trustor_user_id: trustor_user_id_query + - trustee_user_id: trustee_user_id_query -:: +Response +-------- - GET /v3/OS-TRUST/trusts?trustor_user_id=a0fdfd - -In order to list trusts for a given trustee, filter the collection using a query string -(e.g., ``?trustee_user_id={user_id}``). - -:: - - GET /v3/OS-TRUST/trusts?trustee_user_id=86c0d5 - -Response Parameters -------------------- +Parameters +~~~~~~~~~~ .. rest_parameters:: parameters.yaml @@ -212,8 +223,25 @@ Response Parameters - roles_links: roles_links - links: trust_links -Response Example ----------------- +Status Codes +~~~~~~~~~~~~ + +.. rest_status_code:: success ../v3/status.yaml + + - 200 + +.. rest_status_code:: error ../v3/status.yaml + + - 400 + - 401 + - 403 + - 404 + - 405 + - 413 + - 503 + +Example +~~~~~~~ Status: 200 OK @@ -226,23 +254,25 @@ Get trust .. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id} -Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust`` - Gets the trust information for ``{trust_id}``. -Normal response codes: 200 - -Error response codes: 400, 401, 403, 404, 405, 413, 503 +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust`` Request ------- +Parameters +~~~~~~~~~~ + .. rest_parameters:: parameters.yaml - trust_id: trust_id_path -Response Parameters -------------------- +Response +-------- + +Parameters +~~~~~~~~~~ .. rest_parameters:: parameters.yaml @@ -261,8 +291,25 @@ Response Parameters - roles_links: roles_links - links: trust_links -Response Example ----------------- +Status Codes +~~~~~~~~~~~~ + +.. rest_status_code:: success ../v3/status.yaml + + - 200 + +.. rest_status_code:: error ../v3/status.yaml + + - 400 + - 401 + - 403 + - 404 + - 405 + - 413 + - 503 + +Example +~~~~~~~ Status: 200 OK @@ -275,23 +322,25 @@ Delete trust .. rest_method:: DELETE /v3/OS-TRUST/trusts/{trust_id} -Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust`` - Deletes a trust with ``{trust_id}``. -Normal response codes: 204 - -Error response codes: 400, 401, 403, 404, 405, 409, 413, 415, 503 +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust`` Request ------- +Parameters +~~~~~~~~~~ + .. rest_parameters:: parameters.yaml - trust_id: trust_id_path -Response Example ----------------- +Response +-------- + +Example +~~~~~~~ Status: 204 No Content @@ -301,23 +350,42 @@ List roles delegated by a trust .. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles -Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_roles`` - Lists roles delegated by a trust with ``{trust_id}``. -Normal response codes: 200 - -Error response codes: 400, 401, 403, 404, 405, 413, 503 +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_roles`` Request ------- +Parameters +~~~~~~~~~~ + .. rest_parameters:: parameters.yaml - trust_id: trust_id_path -Response Example ----------------- +Response +-------- + +Status Codes +~~~~~~~~~~~~ + +.. rest_status_code:: success ../v3/status.yaml + + - 200 + +.. rest_status_code:: error ../v3/status.yaml + + - 400 + - 401 + - 403 + - 404 + - 405 + - 413 + - 503 + +Example +~~~~~~~ Status: 200 OK @@ -330,53 +398,90 @@ Check if a role is delegated by a trust .. rest_method:: HEAD /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id} -Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role`` - Checks if a role is delegated by a trust. -Normal response codes: 200 - -Error response codes: 400, 401, 403, 404, 405, 413, 503 +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role`` Request ------- +Parameters +~~~~~~~~~~ + .. rest_parameters:: parameters.yaml - trust_id: trust_id_path - role_id: role_id_path -Response Example ----------------- +Response +-------- + +Status Codes +~~~~~~~~~~~~ + +.. rest_status_code:: success ../v3/status.yaml + + - 200 + +.. rest_status_code:: error ../v3/status.yaml + + - 400 + - 401 + - 403 + - 404 + - 405 + - 413 + - 503 + +Example +~~~~~~~ Status: 200 OK - Get role delegated by a trust ============================= .. rest_method:: GET /v3/OS-TRUST/trusts/{trust_id}/roles/{role_id} -Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role`` - Gets a role with delegated by a trust. -Normal response codes: 200 - -Error response codes: 400, 401, 403, 404, 405, 413, 503 +Relationship: ``https://docs.openstack.org/api/openstack-identity/3/ext/OS-TRUST/1.0/rel/trust_role`` Request ------- +Parameters +~~~~~~~~~~ + .. rest_parameters:: parameters.yaml - trust_id: trust_id_path - role_id: role_id_path -Response Example ----------------- +Response +-------- + +Status Codes +~~~~~~~~~~~~ + +.. rest_status_code:: success ../v3/status.yaml + + - 200 + +.. rest_status_code:: error ../v3/status.yaml + + - 400 + - 401 + - 403 + - 404 + - 405 + - 413 + - 503 + +Example +~~~~~~~ Status: 200 OK .. literalinclude:: samples/OS-TRUST/trust-get-role-delegated-response.json - :language: javascript + :language: javascript \ No newline at end of file diff --git a/releasenotes/notes/bug-1747694-48c8caa4871300e3.yaml b/releasenotes/notes/bug-1747694-48c8caa4871300e3.yaml new file mode 100644 index 0000000000..0ab8ba63d1 --- /dev/null +++ b/releasenotes/notes/bug-1747694-48c8caa4871300e3.yaml @@ -0,0 +1,7 @@ +--- +fixes: + - | + [`bug 1747694 `_] + The trust API reference declared support for ``page`` and ``per_page`` + query parameters, when the actual trust API didn't support them. The + API reference has been updated accordingly. \ No newline at end of file