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
This commit is contained in:
Gage Hugo 2016-07-13 12:30:38 -05:00 committed by Steve Martinelli
parent be86bb1206
commit caa7faf160
10 changed files with 710 additions and 0 deletions

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -0,0 +1,10 @@
{
"endpoint_group": {
"description": "endpoint group description",
"filters": {
"interface": "admin",
"service_id": "1b501"
}
"name": "endpoint group name"
}
}

View File

@ -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"
}
}

View File

@ -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
}
}

View File

@ -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"
}
}

View File

@ -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
}
}

View File

@ -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
}
}

View File

@ -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
}
}