From 007e5761c813898fa762150c0467c6855d054542 Mon Sep 17 00:00:00 2001 From: johnsom Date: Mon, 13 Feb 2017 15:28:29 -0800 Subject: [PATCH] Adds v2 general API information section This patch add the general information section to the v2 API reference. Change-Id: I7b780d4afaa19801d800ab24f5c6ab922b57a7e2 Partial-Bug: #1558385 --- .../source/examples/versions-get-resp.json | 14 + api-ref/source/http-status.yaml | 6 + api-ref/source/index.rst | 45 ++ api-ref/source/parameters.yaml | 29 + api-ref/source/v2/general.inc | 531 ++++++++++++++++++ api-ref/source/v2/index.rst | 6 +- 6 files changed, 629 insertions(+), 2 deletions(-) create mode 100644 api-ref/source/examples/versions-get-resp.json create mode 100644 api-ref/source/http-status.yaml create mode 100644 api-ref/source/parameters.yaml create mode 100644 api-ref/source/v2/general.inc diff --git a/api-ref/source/examples/versions-get-resp.json b/api-ref/source/examples/versions-get-resp.json new file mode 100644 index 0000000000..328ed92c23 --- /dev/null +++ b/api-ref/source/examples/versions-get-resp.json @@ -0,0 +1,14 @@ +{ + "versions": [ + { + "id": "v2.0", + "status": "CURRENT", + "updated": "2017-02-17T00:00:00Z" + }, + { + "id": "v1", + "status": "DEPRECATED", + "updated": "2014-12-11T00:00:00Z" + } + ] +} diff --git a/api-ref/source/http-status.yaml b/api-ref/source/http-status.yaml new file mode 100644 index 0000000000..779763055e --- /dev/null +++ b/api-ref/source/http-status.yaml @@ -0,0 +1,6 @@ +200: + default: | + The synchronous request was successful. +500: + default: | + The request encountered an unexpected failure. diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 10fcd5ec8a..40226e9746 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -1,3 +1,4 @@ +:tocdepth: 2 ============= Octavia API @@ -19,3 +20,47 @@ Deprecated API version v2/index v1/index + +.. rest_expand_all:: + +------------- +API Discovery +------------- + +List All Major Versions +======================= + +.. rest_method:: GET / + +This fetches all the information about all known major API versions in the +deployment. + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - id: api_version_id + - status: api_version_status + - updated_at: updated_at + +Response Example +---------------- + +.. literalinclude:: examples/versions-get-resp.json + :language: javascript + +.. note:: + This is just an example output and does not represent the current API + versions available. + +Response codes +-------------- + +.. rest_status_code:: success http-status.yaml + + - 200 + +.. rest_status_code:: error http-status.yaml + + - 500 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 0000000000..532857a111 --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -0,0 +1,29 @@ +api_links: + description: | + Links to the resources in question. + in: body + required: true + type: array +api_version_id: + description: | + A common name for the version. + in: body + required: true + type: string +api_version_status: + description: | + The status of this API version. This can be one of: + + - ``CURRENT``: This is the preferred version of the API to use. + - ``SUPPORTED``: This is an older, but still supported version of the API. + - ``DEPRECATED``: A deprecated version of the API that is slated for + removal. + in: body + required: true + type: string +updated_at: + description: | + The UTC date and timestamp when the resource was last updated. + in: body + required: true + type: string diff --git a/api-ref/source/v2/general.inc b/api-ref/source/v2/general.inc new file mode 100644 index 0000000000..f09144adcf --- /dev/null +++ b/api-ref/source/v2/general.inc @@ -0,0 +1,531 @@ +.. -*- rst -*- + +This section introduces readers to OpenStack Octavia v2.0 ReSTful HTTP API and +provides guidelines on how to use it. + +Service Endpoints +================= + +All API calls described throughout the rest of this document require +authentication with the `OpenStack Identity service +`_. After authentication, the +base ``endpoint URL`` for the ``service type`` of ``load-balancer`` and +``service name`` of ``octavia`` can be extracted from the service catalog +returned with the identity token. + +**Example token snippet with service catalog** + +.. code:: + + { + "token": { + "catalog": [ + { + "endpoints": [ + { + "url": "http://198.51.100.10:9876/", + "interface": "public", + "region": "RegionOne", + "region_id": "RegionOne", + "id": "cd1c3c2dc6434c739ed0a12015373754" + } + ], + "type": "load-balancer", + "id": "1209701aecd3453e9803119cd28cb013", + "name": "octavia" + } + ] + } + } + + +For instance, if the ``endpoint URL`` is ``http://198.51.100.10:9876/`` then +the full API call for ``/v2.0/lbaas/loadbalancers`` is +``http://198.51.100.10:9876/v2.0/lbaas/loadbalancers``. + +Depending on the deployment, the ``load-balancer`` ``endpoint URL`` might be +http or https, a custom port, a custom path, and include your tenant id. The +only way to know the URLs for your deployment is by using the service catalog. +The ``load-balancer`` ``endpoint URL`` should never be hard coded in +applications, even if they are only expected to work at a single site. It +should always be discovered from the Identity token. + +As such, for the rest of this document we will be using short hand where ``GET +/v2.0/lbaas/loadbalancers`` really means ``GET +{your_load-balancer_endpoint_URL}/v2.0/lbaas/loadbalancers``. + +Neutron-lbaas and Octavia v2 APIs +================================= + +The Octavia v2 API is fully backward compatible with the neutron-lbaas v2 API +and is a superset of the neutron-lbaas v2 API. This is intended to provide a +simple migration path for deployments currently using the neutron-lbaas v2 API. +You can update the endpoint your application is using from the keystone +service catalog to use the ``octavia`` endpoint instead of the ``neutron`` +endpoint for load balancer activities. + +During the neutron-lbaas deprecation period a pass-through proxy will be +included in neutron to allow requests via neutron and the neutron-lbaas v2 API +to continue to function. Users are strongly encouraged to update their +applications to access load balancing via the Octavia v2 API. + +.. warning:: + + Load balancing functions accessed via the neutron endpoint are deprecated + and will be removed in a future release. Users are strongly encouraged to + migrate to using the octavia endpoint. + +Authentication and authorization +================================ + +The Octavia API v2.0 uses the `OpenStack Identity service +`_ as the default authentication +service. When Keystone is enabled, users that submit requests to the Octavia +service must provide an authentication token in **X-Auth-Token** request +header. You obtain the token by authenticating to the Keystone endpoint. + +When Keystone is enabled, the ``project_id`` attribute is not required in create +requests because the project ID is derived from the authentication token. + +NOTE: Currently the Octavia API accepts the deprecated ``tenant_id`` +attribute for the project ID for backward compatibility. + +The default authorization settings allow only administrative users to create +resources on behalf of a different project. + +Octavia uses information received from Keystone to authorize user requests. +Octavia Networking handles the following types of authorization policies: + +- **Operation-based policies** specify access criteria for specific + operations, possibly with fine-grained control over specific attributes. + +- **Resource-based policies** access a specific resource. Permissions might or + might not be granted depending on the permissions configured for the + resource. Currently available for only the network resource. + +The actual authorization policies enforced in Octavia might vary from +deployment to deployment. + +Request and response formats +============================ + +The Octavia API v2.0 supports JSON data serialization request and response +formats only. + +Request format +-------------- + +The Octavia API v2.0 only accepts requests with the JSON data serialization +format. The ``Content-Type`` header is ignored. + +Tenant and project attributes in requests +----------------------------------------- + +Starting with the Newton release of the Octavia service, the Octavia API +accepts the ``project_id`` attribute in addition to the ``tenant_id`` attribute +in requests. The ``tenant_id`` attribute is accepted for backward compatibility. +If both the ``project_id`` and the ``tenant_id`` attribute are provided in the +same request, ``project_id`` will be used. + +The ``tenant_id`` attribute is deprecated and will be removed in a future +release. + +Response format +--------------- + +The Octavia API v2.0 always responds with the JSON data serialization +format. The ``Accept`` header is ignored. + +Query extension + A ``.json`` extension can be added to the request URI. For example, the + ``.json`` extension in the following requests are equivalent: + + - **GET** *publicURL*/loadbalancers + + - **GET** *publicURL*/loadbalancers.json + +Tenant and project attributes in responses +------------------------------------------ + +Starting with the Newton release of the Octavia service, the Octavia API +returns a ``project_id`` attribute in responses, while still returning a +``tenant_id`` attribute for backward compatibility. The values will always be +identical. + +The ``tenant_id`` attribute is deprecated and will be removed in a future +release. + + +.. _filtering: + +Filtering and column selection +============================== + +The Octavia API v2.0 supports filtering based on all top level attributes of +a resource. Filters are applicable to all list requests. + +For example, the following request returns all loadbalancers named ``foobar``: + +.. code:: + + GET /v2.0/lbaas/loadbalancers?name=foobar + +When you specify multiple filters, the Octavia API v2.0 returns only objects +that meet all filtering criteria. The operation applies an AND condition among +the filters. + +Note +---- + +Octavia does not offer an OR mechanism for filters. + +Alternatively, you can issue a distinct request for each filter and build a +response set from the received responses on the client-side. + +By default, Octavia returns all attributes for any show or list call. The +Octavia API v2.0 has a mechanism to limit the set of attributes returned. +For example, return ``id``. + +You can use the ``fields`` query parameter to control the attributes returned +from the Octavia API v2.0. + +For example, the following request returns only ``id`` and ``name`` for each +load balancer: + +.. code:: + + GET /v2.0/lbaas/loadbalancers.json?fields=id&fields=name + +Synchronous versus asynchronous plug-in behavior +================================================ + +The Octavia API v2.0 presents a logical model of load balancers consisting +of listeners, pools, and members. It is up to the OpenStack Octavia plug-in +to communicate with the underlying infrastructure to ensure load balancing +is consistent with the logical model. A plug-in might perform these +operations asynchronously. + +When an API client modifies the logical model by issuing an HTTP **POST**, +**PUT**, or **DELETE** request, the API call might return before the plug-in +modifies underlying virtual and physical load balancing devices. However, an +API client is guaranteed that all subsequent API calls properly reflect the +changed logical model. + +For example, if a client issues an HTTP **PUT** request to set the weight +of a member, there is no guarantee that the new weight will be in effect when +the HTTP call returns. This is indicated by an HTTP response code of 202. + +You can use the ``provisioning_status`` attribute to determine whether the +Octavia plug-in has successfully completed the configuration of the resource. + +Bulk-create +=========== + +The Octavia v2.0 API does not support bulk create. You cannot create more than +one load balancer per API call. + +The Octavia v2.0 API does support single call create which allows you to +create a fully populated load balancer in one API call. This is discussed +in the load balancer create section of this reference. + +Pagination +========== + +To reduce load on the service, list operations will return a maximum number of +items at a time. To navigate the collection, the parameters limit, marker and +page\_reverse can be set in the URI. For example: + +.. code:: + + ?limit=100&marker=1234&page_reverse=False + +The ``marker`` parameter is the ID of the last item in the previous list. The +``limit`` parameter sets the page size. The ``page_reverse`` parameter sets +the page direction. These parameters are optional. If the client requests a +limit beyond the maximum limit configured by the deployment, the server returns +the maximum limit number of items. + +For convenience, list responses contain atom "next" links and "previous" links. +The last page in the list requested with 'page\_reverse=False' will not contain +"next" link, and the last page in the list requested with 'page\_reverse=True' +will not contain "previous" link. The following examples illustrate two pages +with three items. The first page was retrieved through: + +.. code:: + + GET http://198.51.100.10:9876/v2.0/lbaas/loadbalancers.json?limit=2 + +If a particular plug-in does not support pagination operations the Octavia API +v2.0 will emulate the pagination behavior so that users can expect the same +behavior regardless of the particular plug-in running in the background. + +**Example load balancer list, first page: JSON request** + +.. code:: + + GET /v2.0/lbaas/loadbalancers.json?limit=2 HTTP/1.1 + Host: 198.51.100.10:9876 + Content-Type: application/json + Accept: application/json + + +**Example load balancer list, first page: JSON response** + +.. code:: + + { + "loadbalancers": [ + { + "admin_state_up": true, + "listeners": [], + "vip_subnet_id": "08dce793-daef-411d-a896-d389cd45b1ea", + "pools": [], + "provider": "octavia", + "description": "Best App load balancer 1", + "name": "bestapplb1", + "operating_status": "ONLINE", + "id": "34d5f4a5-cbbc-43a0-878f-b8a26370e6e7", + "provisioning_status": "ACTIVE", + "vip_port_id": "1e20d91d-8df9-4c15-9778-28bc89226c19", + "vip_address": "203.0.113.10", + "tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f", + "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f" + }, + { + "admin_state_up": true, + "listeners": [], + "vip_subnet_id": "08dce793-daef-411d-a896-d389cd45b1ea", + "pools": [], + "provider": "octavia", + "description": "Second Best App load balancer 1", + "name": "2ndbestapplb1", + "operating_status": "ONLINE", + "id": "0fdb0ca7-0a38-4aea-891c-daaed40bcafe", + "provisioning_status": "ACTIVE", + "vip_port_id": "21f7ac04-6824-4222-93cf-46e0d70607f9", + "vip_address": "203.0.113.20", + "tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f", + "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f" + } + ], + "loadbalancers_links": [ + { + "href": "http://198.51.100.10:9876/v2.0/lbaas/loadbalancers.json?limit=2&marker=0fdb0ca7-0a38-4aea-891c-daaed40bcafe", + "rel": "next" + }, + { + "href": "http://198.51.100.10:9876/v2.0/lbaas/loadbalancers.json?limit=2&marker=34d5f4a5-cbbc-43a0-878f-b8a26370e6e7&page_reverse=True", + "rel": "previous" + } + ] + } + + +The last page won't show the "next" links + +**Example load balancer list, last page: JSON request** + +.. code:: + + GET /v2.0/lbaas/loadbalancers.json?limit=2&marker=4ef465f3-0233-44af-b93d-9d3eae4daf85 HTTP/1.1 + Host: 198.51.100.10:9876 + Content-Type: application/json + Accept: application/json + + + +**Example load balancer list, last page: JSON response** + +.. code:: + + { + "loadbalancers": [ + { + "admin_state_up": true, + "listeners": [], + "vip_subnet_id": "08dce793-daef-411d-a896-d389cd45b1ea", + "pools": [], + "provider": "octavia", + "description": "Other App load balancer 1", + "name": "otherapplb1", + "operating_status": "ONLINE", + "id": "4ef465f3-0233-44af-b93d-9d3eae4daf85", + "provisioning_status": "ACTIVE", + "vip_port_id": "f777a1c7-7f59-4a36-ad34-24dfebaf19e6", + "vip_address": "203.0.113.50", + "tenant_id": "bf325b04-e7b1-4002-9b10-f4984630367f", + "project_id": "bf325b04-e7b1-4002-9b10-f4984630367f" + } + ], + "loadbalancers_links": [ + { + "href": "http://198.51.100.10:9876/v2.0/lbaas/loadbalancers.json?limit=2&marker=4ef465f3-0233-44af-b93d-9d3eae4daf85&page_reverse=True", + "rel": "previous" + } + ] + } + + +Sorting +======= + +Sorting is determined through the use of the 'sort' query string parameter. The +value of this parameter is a comma-separated list of sort keys. Sort directions +can optionally be appended to each sort key, separated by the ':' character. + +The supported sort directions are either 'asc' for ascending or 'desc' for +descending. + +The caller may (but is not required to) specify a sort direction for each key. +If a sort direction is not specified for a key, then a default is set by the +server. + +For example: + +- Only sort keys specified: + + + ``sort=key1,key2,key3`` + + 'key1' is the first key, 'key2' is the second key, etc. + + Sort directions are defaulted by the server + +- Some sort directions specified: + + + ``sort=key1:asc,key2,key3`` + + Any sort key without a corresponding direction is defaulted + + 'key1' is the first key (ascending order), 'key2' is the second key + (direction defaulted by the server), etc. + +- Equal number of sort keys and directions specified: + + + ``sort=key1:asc,key2:desc,key3:asc`` + + Each key is paired with the corresponding direction + + 'key1' is the first key (ascending order), 'key2' is the second key + (descending order), etc. + +You can also use the ``sort_key`` and ``sort_dir`` parameters to sort the +results of list operations. Currently sorting does not work with extended +attributes of resource. The ``sort_key`` and ``sort_dir`` can be repeated, +and the number of ``sort_key`` and ``sort_dir`` provided must be same. The +``sort_dir`` parameter indicates in which direction to sort. Acceptable +values are ``asc`` (ascending) and ``desc`` (descending). + +If a particular plug-in does not support sorting operations the Octavia API +v2.0 emulates the sorting behavior so that users can expect the same behavior +regardless of the particular plug-in that runs in the background. + + +Response Codes +============== + +The following HTTP response status codes are used by the Octavia v2.0 API. + +Success +------- + ++------+----------------------------------------------------------------+ +| Code | Description | ++======+================================================================+ +| 200 | - The synchronous request was successful | ++------+----------------------------------------------------------------+ +| 202 | - The asynchronous request was accepted and is being processed | ++------+----------------------------------------------------------------+ +| 204 | - The request was successful, no content to return | +| | - The entity was successfully deleted | ++------+----------------------------------------------------------------+ + +Faults +------ + +The Octavia API v2.0 returns an error response if a failure occurs while +processing a request. Octavia uses only standard HTTP error codes. +4\ *nn* errors indicate problems in the particular request being sent from +the client. + ++------+----------------------------------------------------------------+ +| Code | Description | ++======+================================================================+ +| 400 | - Bad request | +| | - Malformed request URI or body requested admin state invalid | +| | - Invalid values entered | +| | - Bulk operations disallowed | +| | - Validation failed | +| | - Method not allowed for request body (such as trying to | +| | update attributes that can be specified at create-time only) | ++------+----------------------------------------------------------------+ +| 401 | - Unauthorized: Access is denied due to invalid credentials | ++------+----------------------------------------------------------------+ +| 403 | - The project is over quota for the request | ++------+----------------------------------------------------------------+ +| 404 | - Not Found | +| | - Non existent URI | +| | - Resource not found | ++------+----------------------------------------------------------------+ +| 409 | - Conflict | +| | - The resource is in an immutable state | ++------+----------------------------------------------------------------+ +| 500 | - Internal server error | ++------+----------------------------------------------------------------+ +| 503 | - Service unavailable | +| | - The project is busy with other requests, try again later | ++------+----------------------------------------------------------------+ + + +Status Codes +============ + +Octavia API v2.0 entities have two status codes present in the response body. +The ``provisioning_status`` describes the lifecycle status of the entity while +the ``operating_status`` provides the observed status of the entity. + +For example, a member may be in a ``provisioning_status`` of ``PENDING_UPDATE`` +and have an ``operating_status`` of ``ONLINE``. This would indicate that an +update operation is occuring on this member and it is in an immutable state +but it is healthy and able to service requests. This situation could occur if +the user made a request to update the weight of the member. + +Operating Status Codes +---------------------- + ++------------+--------------------------------------------------------------+ +| Code | Description | ++============+==============================================================+ +| ONLINE | - Entity is operating normally | +| | - All pool members are healthy | ++------------+--------------------------------------------------------------+ +| OFFLINE | - Entity is administratively disabled | ++------------+--------------------------------------------------------------+ +| DEGRADED | - One or more of the entity's components are in ERROR | ++------------+--------------------------------------------------------------+ +| ERROR | - The entity has failed | +| | - The member is failing it's health monitoring checks | +| | - All of the pool members are in ERROR | ++------------+--------------------------------------------------------------+ +| NO_MONITOR | - No health monitor is configured for this entity and it's | +| | status is unknown | ++------------+--------------------------------------------------------------+ + +Provisioning Status Codes +------------------------- + ++----------------+----------------------------------------------------------+ +| Code | Description | ++================+==========================================================+ +| ACTIVE | - The entity was provisioned successfully | ++----------------+----------------------------------------------------------+ +| DELETED | - The entity has been successfully deleted | ++----------------+----------------------------------------------------------+ +| ERROR | - Provisioning failed | ++----------------+----------------------------------------------------------+ +| PENDING_CREATE | - The entity is being created | ++----------------+----------------------------------------------------------+ +| PENDING_UPDATE | - The entity is being updated | ++----------------+----------------------------------------------------------+ +| PENDING_DELETE | - The entity is being deleted | ++----------------+----------------------------------------------------------+ + +Entities in a ``PENDING_*`` state are immutable and cannot be modified until +the requested operation completes. The entity will return to the ``ACTIVE`` +provisioning status once the asynchronus operation completes. + +An entity in ``ERROR`` has failed provisioning. The entity may be deleted and +recreated. diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 69b36c16ac..2efdb1cbd4 100644 --- a/api-ref/source/v2/index.rst +++ b/api-ref/source/v2/index.rst @@ -1,4 +1,4 @@ -:tocdepth: 2 +:tocdepth: 3 ========================== Octavia API v2.0 (Current) @@ -9,6 +9,8 @@ Octavia API v2.0 (Current) -------------------- General API Overview -------------------- +.. include:: general.inc +-------------- Load Balancers -============== +--------------