From c58d771e1c9780e29b68f122da954f52fb5cda35 Mon Sep 17 00:00:00 2001 From: Brant Knudson Date: Sun, 27 Jul 2014 16:09:35 -0500 Subject: [PATCH] Cleanup The resources were split between "Core API" and "Identity". All of these are core APIs so the Identity grouping was removed. Long lines of paragraph text were wrapped at 79 chars for easier reviewing. Change-Id: I423ef0ebd69e546f2dd8d7eac579a57ef591666e --- v3/src/markdown/identity-api-v3.md | 146 ++++++++++++++--------------- 1 file changed, 70 insertions(+), 76 deletions(-) diff --git a/v3/src/markdown/identity-api-v3.md b/v3/src/markdown/identity-api-v3.md index cf077fe7..e6f62a9b 100644 --- a/v3/src/markdown/identity-api-v3.md +++ b/v3/src/markdown/identity-api-v3.md @@ -132,7 +132,7 @@ The resource paths of all collections are plural and are represented at the root of the API (e.g. `/v3/policies`). TCP port 35357 is designated by the Internet Assigned Numbers Authority -("IANA") for use by OpenStack Identity services. Example API requests & +("IANA") for use by OpenStack Identity services. Example API requests and responses in this document therefore assume that the Identity service implementation is deployed at the root of `http://identity:35357/`. @@ -1085,7 +1085,8 @@ Optional attributes: Required attributes for the endpoint object are: - `id`: The endpoint entity id. - - `interface`: The visibility of the endpoint. Should be one of `public`, `internal` or `admin`. + - `interface`: The visibility of the endpoint. Should be one of `public`, + `internal` or `admin`. - `url`: Fully qualified URL of the service endpoint. Optional attributes for the endpoint object are: @@ -1096,9 +1097,9 @@ Optional attributes: Token binding refers to the practice of embedding information from external authentication providers (like a company's Kerberos server) inside the token - such that a client may validate that the token is used in conjunction with that - authentication mechanism. By coupling this authentication we can prevent re-use - of a stolen token as an attacker would not have access to the external + such that a client may validate that the token is used in conjunction with + that authentication mechanism. By coupling this authentication we can prevent + re-use of a stolen token as an attacker would not have access to the external authentication. Specifies one or more external authorization mechanisms that can be used @@ -1124,9 +1125,9 @@ Optional attributes: "algorithm": "sha1" } - the ``fingerprint`` is the hash of the client certificate to be validated in - the specified algorithm. It should be the hex form without separating spaces - or colons. The only supported ``algorithm`` is currently ``sha1``. + the ``fingerprint`` is the hash of the client certificate to be validated + in the specified algorithm. It should be the hex form without separating + spaces or colons. The only supported ``algorithm`` is currently ``sha1``. Example entity: @@ -1227,7 +1228,7 @@ Response: Use cases: -- Given a user name & password, get a token to represent the user. +- Given a user name and password, get a token to represent the user. - Given a token, get a list of other domain/projects the user can access. - Given a token, validate the token and return user, domain, project, roles and potential endpoints. @@ -1498,8 +1499,8 @@ token will be issued without an explicit scope of authorization. *New in version 3.1* If the caller specifies a `nocatalog` query parameter in the authentication request, then the authentication response will not contain -the service catalog. The service catalog will otherwise be included in the response -by default. +the service catalog. The service catalog will otherwise be included in the +response by default. ##### Authentication responses @@ -1786,8 +1787,8 @@ token was issued by `POST /auth/tokens`. *New in version 3.2* -To validate a token using the Identity API without returning a service catalog in the -response. The request has the same format as `GET /auth/tokens`. +To validate a token using the Identity API without returning a service catalog +in the response. The request has the same format as `GET /auth/tokens`. The Identity service will return the exact same response as when the subject token was issued by `POST /auth/tokens?nocatalog`. @@ -2101,8 +2102,8 @@ Response: #### Update service: `PATCH /services/{service_id}` -The request block is the same as the one for create service, except that only the attributes -that are being updated need to be included. +The request block is the same as the one for create service, except that only +the attributes that are being updated need to be included. Response: @@ -2227,8 +2228,8 @@ Response: #### Update endpoint: `PATCH /endpoints/{endpoint_id}` -The request block is the same as the one for create endpoint, except that only the -attributes that are being updated need to be included. +The request block is the same as the one for create endpoint, except that only +the attributes that are being updated need to be included. Response: @@ -2255,15 +2256,6 @@ Response: Status: 204 No Content -## Identity - -The key use cases we need to cover: - -- CRUD on a user -- associating a user with a project -- CRUD on a domain -- CRUD on a project - ### Domains #### List domains: `GET /domains` @@ -2353,8 +2345,8 @@ Response: #### Update domain: `PATCH /domains/{domain_id}` -The request block is the same as the one for create domain, except that only the attributes -that are being updated need to be included. +The request block is the same as the one for create domain, except that only +the attributes that are being updated need to be included. Request: @@ -2382,15 +2374,14 @@ Response: #### Delete domain: `DELETE /domains/{domain_id}` -Deleting a domain will delete all the entities owned by it (Users, -Groups & Projects), as well as any Credentials and Role grants that -relate to these entities. +Deleting a domain will delete all the entities owned by it (Users, Groups, and +Projects), as well as any credentials and role grants that relate to these +entities. -In order to minimize the risk of an inadvertent deletion of a -domain and its entities, a domain must first be disabled (using the -update domain API) before a successful delete domain API call can -be made. Attempting to delete an enabled domain will result in an -HTTP 403 Forbidden response. +In order to minimize the risk of an inadvertent deletion of a domain and its +entities, a domain must first be disabled (using the update domain API) before +a successful delete domain API call can be made. Attempting to delete an +enabled domain will result in an HTTP 403 Forbidden response. Response: @@ -2488,8 +2479,8 @@ Response: #### Update project: `PATCH /projects/{project_id}` -The request block is the same as the one for create project, except that only the attributes -that are being updated need to be included. +The request block is the same as the one for create project, except that only +the attributes that are being updated need to be included. Request: @@ -2704,10 +2695,10 @@ Response: #### Update user: `PATCH /users/{user_id}` -The request block is the same as the one for create user, except that only the attributes -that are being updated need to be included. Use this method attempt to update user -password or enable/disable the user. This may return a HTTP 501 Not Implemented if the -back-end driver does not allow for the functionality. +The request block is the same as the one for create user, except that only the +attributes that are being updated need to be included. Use this method attempt +to update user password or enable/disable the user. This may return a HTTP 501 +Not Implemented if the back-end driver does not allow for the functionality. Response: @@ -2890,9 +2881,9 @@ Response: #### Update group: `PATCH /groups/{group_id}` -The request block is the same as the one for create group, except that only the attributes -that are being updated need to be included. This may return a HTTP 501 Not Implemented -if the back-end driver doesn't allow for the functionality. +The request block is the same as the one for create group, except that only the +attributes that are being updated need to be included. This may return a HTTP +501 Not Implemented if the back-end driver doesn't allow for the functionality. Response: @@ -3030,8 +3021,8 @@ Response: #### Update credential: `PATCH /credentials/{credential_id}` -The request block is the same as the one for create credential, except that only the -attributes that are being updated need to be included. +The request block is the same as the one for create credential, except that +only the attributes that are being updated need to be included. Response: @@ -3139,8 +3130,8 @@ Response: #### Update role: `PATCH /roles/{role_id}` -The request block is the same as the one for create role, except that only the attributes -that are being updated need to be included. +The request block is the same as the one for create role, except that only the +attributes that are being updated need to be included. Response: @@ -3418,35 +3409,38 @@ Response: } } -Since this list is likely to be very long, this API would typically always be used with -one of more of the filter queries. Some typical examples are: +Since this list is likely to be very long, this API would typically always be +used with one of more of the filter queries. Some typical examples are: -`GET /role_assignments?user.id={user_id}` would list all role assignments involving the -specified user. +`GET /role_assignments?user.id={user_id}` would list all role assignments +involving the specified user. -`GET /role_assignments?scope.project.id={project_id}` would list all role assignments -involving the specified project. +`GET /role_assignments?scope.project.id={project_id}` would list all role +assignments involving the specified project. -Each role assignment entity in the collection contains a link to the assignment that gave -rise to this entity. +Each role assignment entity in the collection contains a link to the assignment +that gave rise to this entity. -If the query parameter `effective` is specified, rather than simply returning a list of -role assignments that have been made, the API returns a list of effective assignments at -the user, project and domain level, having allowed for the effects of group membership. -Since the effects of group membership have already been allowed for, the group role -assignment entities themselves will not be returned in the collection. This represents the -effective role assignments that would be included in a scoped token. The same set of query -parameters can also be used in combination with the `effective` parameter. For example: +If the query parameter `effective` is specified, rather than simply returning a +list of role assignments that have been made, the API returns a list of +effective assignments at the user, project and domain level, having allowed for +the effects of group membership. Since the effects of group membership have +already been allowed for, the group role assignment entities themselves will +not be returned in the collection. This represents the effective role +assignments that would be included in a scoped token. The same set of query +parameters can also be used in combination with the `effective` parameter. For +example: -`GET /role_assignments?user.id={user_id}&effective` would, in other words, answer the -question "what can this user actually do?". +`GET /role_assignments?user.id={user_id}&effective` would, in other words, +answer the question "what can this user actually do?". -`GET /role_assignments?user.id={user_id}&scope.project.id={project_id}&effective` would -return the equivalent set of role assignments that would be included in the token response -of a project scoped token. +`GET +/role_assignments?user.id={user_id}&scope.project.id={project_id}&effective` +would return the equivalent set of role assignments that would be included in +the token response of a project scoped token. -An example response for an API call with the query parameter `effective` specified is -given below: +An example response for an API call with the query parameter `effective` +specified is given below: Response: @@ -3495,9 +3489,9 @@ Response: } } -The entity `links` section of a response using the `effective` query parameter also contains, -for entities that are included by virtue of group membership, a url that can be used to -access the membership of the group. +The entity `links` section of a response using the `effective` query parameter +also contains, for entities that are included by virtue of group membership, a +url that can be used to access the membership of the group. ### Policies @@ -3584,8 +3578,8 @@ Response: #### Update policy: `PATCH /policies/{policy_id}` -The request block is the same as the one for create policy, except that only the attributes -that are being updated need to be included. +The request block is the same as the one for create policy, except that only +the attributes that are being updated need to be included. Response: