diff --git a/openstack-identity-api/v3/src/markdown/identity-api-v3.md b/openstack-identity-api/v3/src/markdown/identity-api-v3.md index 385258d2..9a7aae5c 100644 --- a/openstack-identity-api/v3/src/markdown/identity-api-v3.md +++ b/openstack-identity-api/v3/src/markdown/identity-api-v3.md @@ -288,11 +288,11 @@ plural form of the resource name (identical to that found in the resource URL): ##### List Entities filtered by attribute Beyond each resource's canonically unique identifier (the `id` attribute), not -all attributes are guaranteed unique on their own. To list resources which match -a specified attribute value, we can perform a filter query using a query string -with one or more attribute/value pairs: +all attributes are guaranteed unique on their own. To filter a list of +resources based on a specific attribute, we can perform a filtered query using +one or more query parameters: - GET /entities?name={entity_name}&enabled={entity_enabled} + GET /entities?name={entity_name}&enabled If multiple filters are specified in a query, then all filters must match for an entity to be included in the response. The values specified in a filter @@ -1711,7 +1711,9 @@ The key use cases we need to cover: #### List regions: `GET /regions` -query filter for "parent_region_id" (optional) +Optional query parameters: + +- `parent_region_id` (string) Response: @@ -1863,7 +1865,9 @@ Response: #### List services: `GET /services` -query filter for "type" (optional) +Optional query parameters: + +- `type` (string) Response: @@ -1971,7 +1975,10 @@ Response: #### List endpoints: `GET /endpoints` -query filter for "interface" and "service_id" (optional) +Optional query parameters: + +- `interface` (string) +- `service_id` (string) Response: @@ -2108,7 +2115,10 @@ Response: #### List domains: `GET /domains` -query filter for "name" and "enabled" (optional) +Optional query parameters: + +- `enabled` (key-only, no value expected) +- `name` (string) Response: @@ -2231,7 +2241,11 @@ Response: #### List projects: `GET /projects` -query filter for "domain_id", "enabled", "name" (optional) +Optional query parameters: + +- `domain_id` (string) +- `enabled` (key-only, no value expected) +- `name` (string) Response: @@ -2348,7 +2362,12 @@ Response: #### List users: `GET /users` -query filter for "domain_id", "email", "enabled", "name" (optional) +Optional query parameters: + +- `domain_id` (string) +- `email` (string) +- `enabled` (key-only, no value expected) +- `name` (string) Response: @@ -2411,7 +2430,10 @@ Response: #### List user projects: `GET /users/{user_id}/projects` -query filter for "name", "enabled" on project resources (optional) +Optional query parameters: + +- `enabled` (key-only, no value expected) +- `name` (string) Response: @@ -2447,7 +2469,9 @@ Response: #### List groups of which a user is a member: `GET /users/{user_id}/groups` -query filter for "name" (optional) +Optional query parameters: + +- `name` (string) Response: @@ -2560,7 +2584,10 @@ Response: #### List groups: `GET /groups` -query filter for "domain_id", "name" (optional) +Optional query parameters: + +- `domain_id` (string) +- `name` (string) Response: @@ -2622,7 +2649,11 @@ Response: #### List users who are members of a group: `GET /groups/{group_id}/users` -query filter for "name", "enabled", "email" (optional) +Optional query parameters: + +- `email` (string) +- `enabled` (key-only, no value expected) +- `name` (string) Response: @@ -2863,7 +2894,9 @@ Response: #### List roles: `GET /roles` -query filter for "name" (optional) +Optional query parameters: + +- `name` (string) Response: @@ -3128,12 +3161,21 @@ Response: #### List effective role assignments: `GET /role_assignments` -query_filter: group.id, role.id, scope.domain.id, scope.project.id, user.id (all optional) -query_string: effective (optional, default false) +*New in version 3.1* -Get a list of role assignments. This API is only available from v3.1 onwards. +Optional query parameters: -If no query filters are specified, then this API will return a list of all role assignments. +- `group.id` (string) +- `role.id` (string) +- `scope.domain.id` (string) +- `scope.project.id` (string) +- `user.id` (string) +- `effective` (key only, no value expected) + +Get a list of role assignments. + +If no query parameters are specified, then this API will return a list of all +role assignments. Response: @@ -3193,13 +3235,13 @@ involving the specified project. Each role assignment entity in the collection contains a link to the assignment that gave rise to this entity. -If the query_string `effective` is specified then, rather than simply returning a list of +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 -filters can also be used with the `effective` query string. For example: +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?". @@ -3208,7 +3250,7 @@ question "what can this user actually do?". 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_string `effective` specified is +An example response for an API call with the query parameter `effective` specified is given below: Response: @@ -3258,7 +3300,7 @@ Response: } } -The entity `links` section of a response using the `effective` query string also contains, +The entity `links` section of a response using the `effective` query parameter also contains, for entities that are included by virtue of group memebership, a url that can be used to access the membership of the group. @@ -3294,7 +3336,9 @@ Response: #### List policies: `GET /policies` -query filter for "type" (optional) +Optional query parameters: + +- `type` (string) Response: