From caa7faf160426fe5db7cd6414fde319c71006408 Mon Sep 17 00:00:00 2001 From: Gage Hugo Date: Wed, 13 Jul 2016 12:30:38 -0500 Subject: [PATCH] Add OS-EP-FILTER to api-ref Added the missing OS-EP-FILTER extension for Identity v3 to the api-ref docs. Change-Id: I29ef91ce1f37af5233c85168cafc08aee61a5a93 Closes-Bug: #1532220 --- api-ref/source/v3-ext/ep-filter.inc | 506 ++++++++++++++++++ api-ref/source/v3-ext/index.rst | 2 + api-ref/source/v3-ext/parameters.yaml | 27 + .../create-endpoint-group-request.json | 10 + .../OS-EP-FILTER/endpoint-group-response.json | 14 + .../endpoint-groups-response.json | 36 ++ .../endpoint-project-response.json | 12 + .../OS-EP-FILTER/get-projects-response.json | 29 + .../OS-EP-FILTER/list-endpoints-response.json | 29 + .../OS-EP-FILTER/list-service-endpoints.json | 45 ++ 10 files changed, 710 insertions(+) create mode 100644 api-ref/source/v3-ext/ep-filter.inc create mode 100644 api-ref/source/v3-ext/samples/OS-EP-FILTER/create-endpoint-group-request.json create mode 100644 api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-group-response.json create mode 100644 api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-groups-response.json create mode 100644 api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-project-response.json create mode 100644 api-ref/source/v3-ext/samples/OS-EP-FILTER/get-projects-response.json create mode 100644 api-ref/source/v3-ext/samples/OS-EP-FILTER/list-endpoints-response.json create mode 100644 api-ref/source/v3-ext/samples/OS-EP-FILTER/list-service-endpoints.json diff --git a/api-ref/source/v3-ext/ep-filter.inc b/api-ref/source/v3-ext/ep-filter.inc new file mode 100644 index 0000000000..b8952e7794 --- /dev/null +++ b/api-ref/source/v3-ext/ep-filter.inc @@ -0,0 +1,506 @@ +.. -*- rst -*- + +================ +OS-EP-FILTER API +================ + +This API enables creation of ad-hoc catalogs for each project-scoped token +request. To do so, this API uses either static project-endpoint associations +or dynamic custom endpoints groups to associate service endpoints with +projects. + +API Resources +============= + +Endpoint Group +-------------- + +Represents a dynamic collection of service endpoints having the same +characteristics, such as ``service_id``, ``interface``, or ``region``. Indeed, +any endpoint attribute could be used as part of a filter. + +A classic use case is to filter endpoints based on region. For example, suppose +a user wants to filter service endpoints returned in the service catalog by +region, the following endpoint group may be used: + +.. literalinclude:: samples/OS-EP-FILTER/create-endpoint-group-request.json + :language: javascript + +This implies an Endpoint Group with filtering criteria of:: + + ``region_id = "1b501"`` + +Create Association +================== + +.. rest_method:: PUT /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id} + +Creates an association between ``project_id`` and ``endpoint_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint`` + +Normal response codes: 204 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id + - endpoint_id: endpoint_id + +Response +-------- + +Status: 204 No Content + +Check Association +================= + +.. rest_method:: HEAD /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id} + +Verifies the existence of an association between ``project_id`` and ``endpoint_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint`` + +Normal response codes: 204 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id + - endpoint_id: endpoint_id + +Response +-------- + +Status: 204 No Content + +Delete Association +================== + +.. rest_method:: DELETE /v3/OS-EP-FILTER/projects/{project_id}/endpoints/{endpoint_id} + +Removes the association between ``project_id`` and ``endpoint_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint`` + +Normal response codes: 204 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id + - endpoint_id: endpoint_id + +Response +-------- + +Status: 204 No Content + +List Associations for Project +============================= + +.. rest_method:: GET /v3/OS-EP-FILTER/projects/{project_id}/endpoints + +Returns all the endpoints that are currently associated with ``project_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoints`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id + - endpoint_id: endpoint_id + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/list-endpoints-response.json + :language: javascript + +Get projects associated with endpoint +===================================== + +.. rest_method:: GET /v3/OS-EP-FILTER/endpoints/{endpoint_id}/projects + +Returns all projects that are currently associated with ``endpoint_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_projects`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_id: endpoint_id + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/get-projects-response.json + :language: javascript + +Create Endpoint Group +===================== + +.. rest_method:: POST /v3/OS-EP-FILTER/endpoint_groups + +Create a new endpoint group filter that represents a dynamic collection of +service endpoints having the same characteristics + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_groups`` + +Normal response codes: 201 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - name: eg_name + - filters: eg_filters + - description: eg_description + +.. literalinclude:: samples/OS-EP-FILTER/create-endpoint-group-request.json + :language: javascript + +Response +-------- + +Status: 201 Created + +.. literalinclude:: samples/OS-EP-FILTER/endpoint-group-response.json + :language: javascript + +Get Endpoint Group +================== + +.. rest_method:: GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id} + +Show details of an endpoint group. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters: parameters.yaml + + - endpoint_group_id: endpoint_group_id + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/endpoint-group-response.json + :language: javascript + +Check Endpoint Group +==================== + +.. rest_method:: HEAD /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id} + +Determine if an endpoint group exists. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + +Response +-------- + +Status: 200 OK + +Update Endpoint Group +===================== + +.. rest_method:: PATCH /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id} + +Modify attributes of an endpoint group. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + - name: eg_name + - filters: eg_filters + - description: eg_description + +.. literalinclude:: samples/OS-EP-FILTER/create-endpoint-group-request.json + :language: javascript + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/endpoint-group-response.json + :language: javascript + +Delete Endpoint Group +===================== + +.. rest_method:: DELETE /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id} + +Delete an endpoint group. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group`` + +Normal response codes: 204 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + +Response +-------- + +Status: 204 No Content + +List Endpoint Groups +==================== + +.. rest_method:: GET /v3/OS-EP-FILTER/endpoint_groups + +List all available endpoint groups. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_groups`` + +Normal response codes: 200 +Error response codes: 401 + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/endpoint-groups-response.json + :language: javascript + +Create Endpoint Group to Project Association +============================================ + +.. rest_method:: PUT /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id} + +Creates an associate between ``endpoint_group_id`` and ``project_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project`` + +Normal response codes: 204 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + - project_id: project_id + +Response +-------- + +Status: 204 No Content + +Get Endpoint Group to Project Association +========================================= + +.. rest_method:: GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id} + +Verifies the existence of an association between ``project_id`` and ``endpoint_group_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + - project_id: project_id + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/endpoint-project-response.json + :language: javascript + +Check Endpoint Group to Project Association +=========================================== + +.. rest_method:: HEAD /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id} + +Verifies the existence of an association between ``project_id`` and ``endpoint_group_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + - project_id: project_id + +Response +-------- + +Status: 200 OK + +Delete Endpoint Group to Project Association +============================================ + +.. rest_method:: DELETE /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects/{project_id} + +Removes the association between ``project_id`` and ``endpoint_group_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_project`` + +Normal response codes: 204 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + - project_id: project_id + +Response +-------- + +Status: 204 No Content + +List Projects Associated with Endpoint Group +============================================ + +.. rest_method:: GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/projects + +Returns all projects that are currently associated with ``endpoint_group_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_projects`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/get-projects-response.json + :language: javascript + +List Endpoints Associated with Endpoint Group +============================================= + +.. rest_method:: GET /v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/endpoints + +Returns all the endpoints that are currently associated with ``endpoint_group_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/endpoint_group_endpoints`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - endpoint_group_id: endpoint_group_id + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/list-service-endpoints.json + :language: javascript + +List Endpoint Groups Associated with Project +============================================ + +.. rest_method:: GET /v3/OS-EP-FILTER/projects/{project_id}/endpoint_groups + +Returns all the endpoints that are currently associated with ``project_id``. + +Relationship: ``http://docs.openstack.org/api/openstack-identity/3/ext/OS-EP-FILTER/1.0/rel/project_endpoint_groups`` + +Normal response codes: 200 +Error response codes: 401 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id + +Response +-------- + +Status: 200 OK + +.. literalinclude:: samples/OS-EP-FILTER/endpoint-groups-response.json + :language: javascript diff --git a/api-ref/source/v3-ext/index.rst b/api-ref/source/v3-ext/index.rst index 24d9135496..1637818c40 100644 --- a/api-ref/source/v3-ext/index.rst +++ b/api-ref/source/v3-ext/index.rst @@ -11,6 +11,7 @@ This page describes these Identity API v3 extensions: * `OS-OAUTH1 API`_ * `OS-TRUST API`_ * `OS-REVOKE API`_ +* `OS-EP-FILTER API`_ .. rest_expand_all:: @@ -19,3 +20,4 @@ This page describes these Identity API v3 extensions: .. include:: oauth.inc .. include:: trust.inc .. include:: revoke.inc +.. include:: ep-filter.inc diff --git a/api-ref/source/v3-ext/parameters.yaml b/api-ref/source/v3-ext/parameters.yaml index 11f5ec6459..2fc420d613 100644 --- a/api-ref/source/v3-ext/parameters.yaml +++ b/api-ref/source/v3-ext/parameters.yaml @@ -19,6 +19,12 @@ domain_id: in: path required: false type: string +endpoint_group_id: + description: | + The UUID of the endpoint group. + in: path + required: false + type: string endpoint_id: description: | The endpoint ID. @@ -118,6 +124,27 @@ description: in: body required: false type: string +eg_description: + description: | + The endpoint group description. + in: body + required: false + type: string +eg_filters: + description: | + Describes the filtering performed by the endpoint group. The filter used must + be an ``endpoint`` property, such as ``interface``, ``service_id``, + ``region_id`` and ``enabled``. Note that if using ``interface`` as a filter, + the only available values are ``public``, ``internal`` and ``admin``. + in: body + required: true + type: object +eg_name: + description: | + User-facing name of the service. + in: body + required: true + type: string endpoints: description: | An ``endpoints`` object. diff --git a/api-ref/source/v3-ext/samples/OS-EP-FILTER/create-endpoint-group-request.json b/api-ref/source/v3-ext/samples/OS-EP-FILTER/create-endpoint-group-request.json new file mode 100644 index 0000000000..4e8820e457 --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-EP-FILTER/create-endpoint-group-request.json @@ -0,0 +1,10 @@ +{ + "endpoint_group": { + "description": "endpoint group description", + "filters": { + "interface": "admin", + "service_id": "1b501" + } + "name": "endpoint group name" + } +} diff --git a/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-group-response.json b/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-group-response.json new file mode 100644 index 0000000000..6bf5d24aec --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-group-response.json @@ -0,0 +1,14 @@ +{ + "endpoint_group": { + "description": "endpoint group description", + "filters": { + "interface": "admin", + "service_id": "1b501a" + }, + "id": "ac4861", + "links": { + "self": "http://identity:35357/v3/OS-EP-FILTER/endpoint_groups/ac4861" + }, + "name": "endpoint group name" + } +} diff --git a/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-groups-response.json b/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-groups-response.json new file mode 100644 index 0000000000..5588395f9c --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-groups-response.json @@ -0,0 +1,36 @@ +{ + "endpoint_groups": [ + { + "endpoint_group": { + "description": "endpoint group description #1", + "filters": { + "interface": "admin", + "service_id": "1b501a" + }, + "id": "ac4861", + "links": { + "self": "http://identity:35357/v3/OS-EP-FILTER/endpoint_groups/ac4861" + }, + "name": "endpoint group name #1" + } + }, + { + "endpoint_group": { + "description": "endpoint group description #2", + "filters": { + "interface": "admin" + }, + "id": "3de68c", + "links": { + "self": "http://identity:35357/v3/OS-EP-FILTER/endpoint_groups/3de68c" + }, + "name": "endpoint group name #2" + } + } + ], + "links": { + "self": "https://identity:35357/v3/OS-EP-FILTER/endpoint_groups", + "previous": null, + "next": null + } +} diff --git a/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-project-response.json b/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-project-response.json new file mode 100644 index 0000000000..cf9d26fc0f --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-EP-FILTER/endpoint-project-response.json @@ -0,0 +1,12 @@ +{ + "project": { + "domain_id": "1789d1", + "enabled": true, + "id": "263fd9", + "links": { + "self": "http://identity:35357/v3/projects/263fd9" + }, + "name": "project name #1", + "description": "project description #1" + } +} diff --git a/api-ref/source/v3-ext/samples/OS-EP-FILTER/get-projects-response.json b/api-ref/source/v3-ext/samples/OS-EP-FILTER/get-projects-response.json new file mode 100644 index 0000000000..0e88b6d4c2 --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-EP-FILTER/get-projects-response.json @@ -0,0 +1,29 @@ +{ + "projects": [ + { + "domain_id": "1789d1", + "enabled": true, + "id": "263fd9", + "links": { + "self": "http://identity:35357/v3/projects/263fd9" + }, + "name": "a project name 1", + "description": "a project description 1" + }, + { + "domain_id": "1789d1", + "enabled": true, + "id": "61a1b7", + "links": { + "self": "http://identity:35357/v3/projects/61a1b7" + }, + "name": "a project name 2", + "description": "a project description 2" + } + ], + "links": { + "self": "http://identity:35357/v3/OS-EP-FILTER/endpoints/6fedc0/projects", + "previous": null, + "next": null + } +} diff --git a/api-ref/source/v3-ext/samples/OS-EP-FILTER/list-endpoints-response.json b/api-ref/source/v3-ext/samples/OS-EP-FILTER/list-endpoints-response.json new file mode 100644 index 0000000000..fd37a5874c --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-EP-FILTER/list-endpoints-response.json @@ -0,0 +1,29 @@ +{ + "endpoints": [ + { + "id": "6fedc0", + "interface": "public", + "url": "http://identity:35357/", + "region": "north", + "links": { + "self": "http://localhost/identity/v3/endpoints/6fedc0" + }, + "service_id": "1b501a" + }, + { + "id": "6fedc0", + "interface": "internal", + "region": "south", + "url": "http://identity:35357/", + "links": { + "self": "http://localhost/identity/v3/endpoints/6fedc0" + }, + "service_id": "1b501a" + } + ], + "links": { + "self": "http://localhost/identity/v3/OS-EP-FILTER/projects/263fd9/endpoints", + "previous": null, + "next": null + } +} diff --git a/api-ref/source/v3-ext/samples/OS-EP-FILTER/list-service-endpoints.json b/api-ref/source/v3-ext/samples/OS-EP-FILTER/list-service-endpoints.json new file mode 100644 index 0000000000..3acf0c0117 --- /dev/null +++ b/api-ref/source/v3-ext/samples/OS-EP-FILTER/list-service-endpoints.json @@ -0,0 +1,45 @@ +{ + "endpoints": [ + { + "enabled": true, + "id": "6fedc0" + "interface": "admin", + "legacy_endpoint_id": "6fedc0", + "links": { + "self": "http://identity:35357/v3/endpoints/6fedc0" + }, + "region": "RegionOne", + "service_id": "1b501a", + "url": "http://localhost:9292" + }, + { + "enabled": true, + "id": "b501aa" + "interface": "internal", + "legacy_endpoint_id": "b501aa", + "links": { + "self": "http://identity:35357/v3/endpoints/b501aa" + }, + "region": "RegionOne", + "service_id": "1b501a", + "url": "http://localhost:9292" + }, + { + "enabled": true, + "id": "b7c573" + "interface": "public", + "legacy_endpoint_id": "b7c573", + "links": { + "self": "http://identity:35357/v3/endpoints/b7c573" + }, + "region": "RegionOne", + "service_id": "1b501a", + "url": "http://localhost:9292" + } + ], + "links": { + "self": "http://identity:35357/v3/OS-EP-FILTER/endpoint_groups/{endpoint_group_id}/endpoints", + "previous": null, + "next": null + } +}