diff options
Diffstat (limited to 'api-guide')
| -rw-r--r-- | api-guide/source/extensions.rst | 150 | ||||
| -rw-r--r-- | api-guide/source/server_concepts.rst | 256 |
2 files changed, 261 insertions, 145 deletions
diff --git a/api-guide/source/extensions.rst b/api-guide/source/extensions.rst index c9615f0dc8..90b6f41e35 100644 --- a/api-guide/source/extensions.rst +++ b/api-guide/source/extensions.rst @@ -2,146 +2,10 @@ Extensions ========== -The OpenStack Compute API v2.0 is extensible. Extensions serve two purposes: -They allow the introduction of new features in the API without requiring -a version change and they allow the introduction of vendor specific -niche functionality. Applications can programmatically list available -extensions by performing a **GET** on the ``/extensions`` URI. Note that -this is a versioned request; that is, an extension available in one API -version might not be available in another. - -Extensions may also be queried individually by their unique alias. This -provides the simplest method of checking if an extension is available -because an unavailable extension issues an itemNotFound (404) -response. - -Extensions may define new data types, parameters, actions, headers, -states, and resources. - -NOTE: Extensions is a deprecated concept in Nova and their support -will be removed in a future version. If your product or cloud relies -on extensions you should work on getting those features into the main -upstream project. - -Important -~~~~~~~~~ - -Applications should ignore response data that contains extension -elements. An extended state should always be treated as an ``UNKNOWN`` -state if the application does not support the extension. Applications -should also verify that an extension is available before submitting an -extended request. - - -**Example: Extended server: JSON response** - -.. code:: - - { - "servers": [ - { - "id": "52415800-8b69-11e0-9b19-734f6af67565", - "tenant_id": "1234", - "user_id": "5678", - "name": "sample-server", - "updated": "2010-10-10T12:00:00Z", - "created": "2010-08-10T12:00:00Z", - "hostId": "e4d909c290d0fb1ca068ffaddf22cbd0", - "status": "BUILD", - "progress": 60, - "accessIPv4" : "67.23.10.132", - "accessIPv6" : "::babe:67.23.10.132", - "image" : { - "id": "52415800-8b69-11e0-9b19-734f6f006e54", - "links": [ - { - "rel": "self", - "href": "http://servers.api.openstack.org/v2/1234/images/52415800-8b69-11e0-9b19-734f6f006e54" - }, - { - "rel": "bookmark", - "href": "http://servers.api.openstack.org/1234/images/52415800-8b69-11e0-9b19-734f6f006e54" - } - ] - }, - "flavor" : { - "id": "52415800-8b69-11e0-9b19-734f216543fd", - "links": [ - { - "rel": "self", - "href": "http://servers.api.openstack.org/v2/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd" - }, - { - "rel": "bookmark", - "href": "http://servers.api.openstack.org/1234/flavors/52415800-8b69-11e0-9b19-734f216543fd" - } - ] - }, - "addresses": { - "public" : [ - { - "version": 4, - "addr": "67.23.10.132" - }, - { - "version": 6, - "addr": "::babe:67.23.10.132" - }, - { - "version": 4, - "addr": "67.23.10.131" - }, - { - "version": 6, - "addr": "::babe:4317:0A83" - } - ], - "private" : [ - { - "version": 4, - "addr": "10.176.42.16" - }, - { - "version": 6, - "addr": "::babe:10.176.42.16" - } - ] - }, - "metadata": { - "Server Label": "Web Head 1", - "Image Version": "2.1" - }, - "links": [ - { - "rel": "self", - "href": "http://servers.api.openstack.org/v2/1234/servers/52415800-8b69-11e0-9b19-734f6af67565" - }, - { - "rel": "bookmark", - "href": "http://servers.api.openstack.org/1234/servers/52415800-8b69-11e0-9b19-734f6af67565" - } - ], - "RS-CBS:volumes": [ - { - "name": "OS", - "href": "https://cbs.api.rackspacecloud.com/12934/volumes/19" - }, - { - "name": "Work", - "href": "https://cbs.api.rackspacecloud.com/12934/volumes/23" - } - ] - } - ] - } - - -**Example: Extended action: JSON response** - -.. code:: - - { - "RS-CBS:attach-volume":{ - "href":"https://cbs.api.rackspacecloud.com/12934/volumes/19" - } - } +Extensions are a deprecated concept in Nova. Support for extensions will be +removed in a future release. In order to keep backwards-compatibility with +legacy V2 API users, the ``extension_info`` API will remain as part of the +Compute API. However, API extensions will not be supported anymore; +there is only one standard API now. For the current V2.1 API, ``Microversions`` +are the new mechanism for implementing API features and changes. For more +detail about microversions, please refer to :doc:`microversions`. diff --git a/api-guide/source/server_concepts.rst b/api-guide/source/server_concepts.rst index bcdc5f5daa..d836debd2b 100644 --- a/api-guide/source/server_concepts.rst +++ b/api-guide/source/server_concepts.rst @@ -125,8 +125,260 @@ operations on the server. Server query ~~~~~~~~~~~~ -TODO: We should introduce that there are multiple methods to filter the -response of list servers. +Nova allows both general user and administrator to filter the server +query result by using query options. + +For general user, ``reservation_id``, ``name``, ``status``, ``image``, +``flavor``, ``ip``, ``changes-since``, ``all_tenants``, +``ip6 (microversion 2.5)`` are supported options to be used. The other +options will be ignored by nova silently only with a debug log. + +For administrator, there are more fields can be used. +Usually the filter is operated on the database schema definition of +``class Instance``, e.g there is a field named 'locked' in the schema +then the filter can use 'locked' as search options to filter servers. +Also, there are some special options such as ``changes-since`` can +be used and interpreted by nova. + +- **General user & Administrator supported options** + General user supported options are listed above and administrator can + use almost all the options except the options parameters for sorting + and pagination. + +.. code:: + Precondition: + there are 2 servers existing in cloud with following info: + + "servers":[ + { + "name": "t1", + "locked": "true", + ... + } + { + "name":"t2", + "locked": "false", + ... + } + + **Example: General user query server with administrator only options** + +.. code:: + Request with non-administrator context: + GET /servers/detail?locked=1 + Note that 'locked' is not returned through API layer + + Response: + { + "servers":[ + { + "name": "t1", + ... + } + { + "name":"t2", + ... + } + ] + } + + **Example: Administrator query server with administrator only options** + +.. code:: + Request with administrator context: + GET /servers/detail?locked=1 + + Response: + { + "servers":[ + { + "name": "t1", + ... + } + ] + } + +- **Exact matching and regex matching of the search options** + + Depending on the name of a filter, matching for that filter is performed + using either exact matching or as regular expression matching. + ``project_id``, ``user_id``, ``image_ref``, ``vm_state``, + ``instance_type_id``, ``uuid``, ``metadata``, ``host``, ``system_metadata`` + are the options that are applied by exact matching when filtering. + + **Example: User query server using exact matching on host** + +.. code:: + Precondition: + Request with administrator context: + GET /servers/detail + + Response: + + { + "servers":[ + { + "name": "t1", + "OS-EXT-SRV-ATTR:host": "devstack" + ... + } + { + "name": "t2", + "OS-EXT-SRV-ATTR:host": "devstack1" + ... + } + ] + } + + Request with administrator context: + GET /servers/detail?host=devstack + + Response: + + { + "servers":[ + { + "name": "t1", + "OS-EXT-SRV-ATTR:host": "devstack" + ... + } + ] + } + + **Example: Query server using regex matching on name** + +.. code:: + Precondition: + Request with administrator context: + GET /servers/detail + + Response: + + { + "servers":[ + { + "name": "test11", + ... + } + { + "name": "test21", + ... + } + { + "name": "t1", + ... + } + { + "name": "t14", + ... + } + ] + } + + Request with administrator context: + GET /servers/detail?name=t1 + + Response: + + { + "servers":[ + { + "name": "test11", + ... + } + { + "name": "t1", + ... + } + { + "name": "t14", + ... + } + ] + } + + **Example: User query server using exact matching on host and + regex matching on name** + +.. code:: + Precondition: + Request with administrator context: + GET /servers/detail + + Response: + + { + "servers":[ + { + "name": "test1", + "OS-EXT-SRV-ATTR:host": "devstack" + ... + } + { + "name": "t2", + "OS-EXT-SRV-ATTR:host": "devstack1" + ... + } + { + "name": "test3", + "OS-EXT-SRV-ATTR:host": "devstack1" + ... + } + ] + } + + Request with administrator context: + GET /servers/detail?host=devstack1&name=test + + Response: + + { + "servers":[ + { + "name": "test3", + "OS-EXT-SRV-ATTR:host": "devstack1" + ... + } + ] + } + +- **Speical keys are used to tweek the query** + ``changes-since`` returns instances updated after the given time, + ``deleted`` return (or exclude) deleted instances and ``soft_deleted`` + modify behavior of 'deleted' to either include or exclude instances whose + vm_state is SOFT_DELETED. Please see: :doc:`polling_changes-since_parameter` + + **Example: User query server with special keys changes-since** + +.. code:: + Precondition: + GET /servers/detail + + Response: + { + "servers":[ + { + "name": "t1" + "updated": "2015-12-15T15:55:52Z" + ... + } + { + "name": "t2", + "updated": "2015-12-17T15:55:52Z" + ... + } + } + + GET /servers/detail?changes-since='2015-12-16T15:55:52Z' + + Response: + { + { + "name": "t2", + "updated": "2015-12-17T15:55:52Z" + ... + } + } Server actions ~~~~~~~~~~~~~~~ |