Browse Source

Improve formats of the Compute API guide

Replace the 'NOTE' and 'TODO' words with
the note and todo directives in the Compute API guide.

Improve some format in the guide.
e.g. Fix unnecessary bold characters.

Change-Id: I7e9d6b8a5228886fd5de03d12482481d2b652666
Closes-Bug: #1558459
changes/09/615809/3
Takashi NATSUME 4 years ago
parent
commit
ddf7c6e370
  1. 6
      api-guide/source/conf.py
  2. 18
      api-guide/source/general_info.rst
  3. 2
      api-guide/source/index.rst
  4. 50
      api-guide/source/microversions.rst
  5. 14
      api-guide/source/paginated_collections.rst
  6. 4
      api-guide/source/polling_changes.rst
  7. 181
      api-guide/source/server_concepts.rst
  8. 16
      api-guide/source/users.rst
  9. 12
      api-guide/source/versions.rst

6
api-guide/source/conf.py

@ -31,7 +31,8 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['openstackdocstheme']
extensions = ['openstackdocstheme',
'sphinx.ext.todo']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@ -39,6 +40,9 @@ templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The 'todo' and 'todolist' directive produce output.
todo_include_todos = True
# The encoding of source files.
# source_encoding = 'utf-8-sig'

18
api-guide/source/general_info.rst

@ -112,19 +112,19 @@ In this section we focus on this related to networking.
- **Port**
TODO
.. todo:: Add more details.
- **Floating IPs, Pools and DNS**
TODO
.. todo:: Add more details.
- **Security Groups**
TODO
.. todo:: Add more details.
- **Extended Networks**
TODO
.. todo:: Add more details.
Administrator Concepts
@ -222,9 +222,9 @@ on compute hosts rather than servers.
- **Hosts**
Hosts are the *physical machines* that provide the resources for the virtual
servers created in Nova. They run a ``hypervisor`` (see definition below)
servers created in Nova. They run a **hypervisor** (see definition below)
that handles the actual creation and management of the virtual servers.
Hosts also run the ``Nova compute service``, which receives requests from
Hosts also run the **Nova compute service**, which receives requests from
Nova to interact with the virtual servers on that machine. When compute
service receives a request, it calls the appropriate methods of the driver
for that hypervisor in order to carry out the request. The driver acts as
@ -282,7 +282,7 @@ Relationship with Volume API
Here we discuss about Cinder's API and how Nova users volume UUIDs.
TODO - add more details.
.. todo:: add more details.
Relationship with Image API
===========================
@ -290,7 +290,7 @@ Relationship with Image API
Here we discuss about Glance's API and how Nova uses image UUIDs.
We also discuss how Nova proxies setting image metadata.
TODO - add more details.
.. todo:: add more details.
Interactions with neutron and nova-network (deprecated)
=======================================================
@ -302,4 +302,4 @@ Here we discuss about Neutron's API and how Nova users port UUIDs.
We also discuss Nova automatically creating ports, proxying security groups,
and proxying floating IPs. Also talk about the APIs we do not proxy.
TODO - add more details.
.. todo:: add more details.

2
api-guide/source/index.rst

@ -60,7 +60,7 @@ the following endpoints:
* / - list of available versions
* /v2 - the first version of the Compute API, uses extensions
(we call this Compute API v2.0)
(we call this Compute API v2.0)
* /v2.1 - same API, except uses microversions
While this guide concentrates on documenting the v2.1 API,

50
api-guide/source/microversions.rst

@ -27,24 +27,24 @@ There are multiple cases which you can resolve with microversions:
- **Older clients with new cloud**
Before using an old client to talk to a newer cloud, the old client can check
the minimum version of microversions to verify whether the cloud is compatible
with the old API. This prevents the old client from breaking with backwards
incompatible API changes.
Currently the minimum version of microversions is `2.1`, which is a
microversion compatible with the legacy v2 API. That means the legacy v2 API
user doesn't need to worry that their older client software will be broken when
their cloud is upgraded with new versions. And the cloud operator doesn't need
to worry that upgrading their cloud to newer versions will break any user with
older clients that don't expect these changes.
Before using an old client to talk to a newer cloud, the old client can check
the minimum version of microversions to verify whether the cloud is
compatible with the old API. This prevents the old client from breaking with
backwards incompatible API changes.
Currently the minimum version of microversions is `2.1`, which is a
microversion compatible with the legacy v2 API. That means the legacy v2 API
user doesn't need to worry that their older client software will be broken
when their cloud is upgraded with new versions. And the cloud operator
doesn't need to worry that upgrading their cloud to newer versions will
break any user with older clients that don't expect these changes.
- **User discovery of available features between clouds**
The new features can be discovered by microversions. The user client should
check the microversions firstly, and new features are only enabled when clouds
support. In this way, the user client can work with clouds that have deployed
different microversions simultaneously.
The new features can be discovered by microversions. The user client should
check the microversions firstly, and new features are only enabled when
clouds support. In this way, the user client can work with clouds that have
deployed different microversions simultaneously.
Version Discovery
=================
@ -52,7 +52,7 @@ Version Discovery
The Version API will return the minimum and maximum microversions. These values
are used by the client to discover the API's supported microversion(s).
Requests to '/' will get version info for all endpoints. A response would look
Requests to `/` will get version info for all endpoints. A response would look
as follows::
{
@ -86,12 +86,12 @@ as follows::
]
}
"version" is the maximum microversion, "min_version" is the minimum
``version`` is the maximum microversion, ``min_version`` is the minimum
microversion. If the value is the empty string, it means this endpoint doesn't
support microversions; it is a legacy v2 API endpoint -- for example, the
endpoint `http://openstack.example.com/v2/` in the above sample. The endpoint
`http://openstack.example.com/v2.1/` supports microversions; the maximum
microversion is '2.14', and the minimum microversion is '2.1'. The client
microversion is `2.14`, and the minimum microversion is `2.1`. The client
should specify a microversion between (and including) the minimum and maximum
microversion to access the endpoint.
@ -117,20 +117,20 @@ following header to specify the microversion::
This acts conceptually like the "Accept" header. Semantically this means:
* If neither `X-OpenStack-Nova-API-Version` nor `OpenStack-API-Version`
* If neither ``X-OpenStack-Nova-API-Version`` nor ``OpenStack-API-Version``
(specifying `compute`) is provided, act as if the minimum supported
microversion was specified.
* If both headers are provided, `OpenStack-API-Version` will be preferred.
* If both headers are provided, ``OpenStack-API-Version`` will be preferred.
* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` is provided,
* If ``X-OpenStack-Nova-API-Version`` or ``OpenStack-API-Version`` is provided,
respond with the API at that microversion. If that's outside of the range
of microversions supported, return 406 Not Acceptable.
* If `X-OpenStack-Nova-API-Version` or `OpenStack-API-Version` has a value
of ``latest`` (special keyword), act as if maximum was specified.
* If ``X-OpenStack-Nova-API-Version`` or ``OpenStack-API-Version`` has a value
of `latest` (special keyword), act as if maximum was specified.
.. warning:: The ``latest`` value is mostly meant for integration testing and
.. warning:: The `latest` value is mostly meant for integration testing and
would be dangerous to rely on in client code since microversions are not
following semver and therefore backward compatibility is not guaranteed.
Clients should always require a specific microversion but limit what is
@ -149,7 +149,7 @@ the response::
The first header specifies the microversion number of the API which was
executed.
The `Vary` header is used as a hint to caching proxies that the response
The ``Vary`` header is used as a hint to caching proxies that the response
is also dependent on the microversion and not just the body and query
parameters. See :rfc:`2616` section 14.44 for details.

14
api-guide/source/paginated_collections.rst

@ -4,18 +4,18 @@ Paginated collections
To reduce load on the service, list operations return a maximum number
of items at a time. The maximum number of items returned is determined
by the compute provider. To navigate the collection, the *``limit``* and
*``marker``* parameters can be set in the URI. For example:
by the compute provider. To navigate the collection, the ``limit`` and
``marker`` parameters can be set in the URI. For example:
.. code::
?limit=100&marker=1234
The *``marker``* parameter is the ID of the last item in the previous
The ``marker`` parameter is the ID of the last item in the previous
list. By default, the service sorts items by create time in descending order.
When the service cannot identify a create time, it sorts items by ID. The
*``limit``* parameter sets the page size. Both parameters are optional. If the
client requests a *``limit``* beyond one that is supported by the deployment
``limit`` parameter sets the page size. Both parameters are optional. If the
client requests a ``limit`` beyond one that is supported by the deployment
an overLimit (413) fault may be thrown. A marker with an invalid ID returns
a badRequest (400) fault.
@ -25,11 +25,11 @@ implementation does not contain ``previous`` links. The last
page in the list does not contain a link to "next" page. The following examples
illustrate three pages in a collection of servers. The first page was
retrieved through a **GET** to
``http://servers.api.openstack.org/v2.1/servers?limit=1``. In these
`http://servers.api.openstack.org/v2.1/servers?limit=1`. In these
examples, the *``limit``* parameter sets the page size to a single item.
Subsequent links honor the initial page size. Thus, a client can follow
links to traverse a paginated collection without having to input the
*``marker``* parameter.
``marker`` parameter.
**Example: Servers collection: JSON (first page)**

4
api-guide/source/polling_changes.rst

@ -10,10 +10,10 @@ for changes within a specified time.
The ``changes-since`` time or ``changes-before`` time is specified as
an `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`__ dateTime
(2011-01-24T17:08Z). The form for the timestamp is **CCYY-MM-DDThh:mm:ss**.
(`2011-01-24T17:08Z`). The form for the timestamp is **CCYY-MM-DDThh:mm:ss**.
An optional time zone may be written in by appending the form ±hh:mm
which describes the timezone as an offset from UTC. When the timezone is
not specified (2011-01-24T17:08), the UTC timezone is assumed.
not specified (`2011-01-24T17:08`), the UTC timezone is assumed.
The following situations need to be considered:

181
api-guide/source/server_concepts.rst

@ -59,9 +59,9 @@ server status is one of the following values:
- ``SHUTOFF``: The server was powered down by the user, either through the
OpenStack Compute API or from within the server. For example, the user
issued a ``shutdown -h`` command from within the server. If the OpenStack
Compute manager detects that the VM was powered down, it transitions the
server to the SHUTOFF status.
issued a :command:`shutdown -h` command from within the server.
If the OpenStack Compute manager detects that the VM was powered down,
it transitions the server to the SHUTOFF status.
- ``SOFT_DELETED``: The server is marked as deleted but will remain in the
cloud for some configurable amount of time. While soft-deleted, an
@ -93,8 +93,8 @@ are exposed to administrators:
Refer to :nova-doc:`VM States <reference/vm-states.html>`.
- task_state represents what is happening to the instance at the
current moment. These tasks can be generic, such as 'spawning', or specific,
such as 'block_device_mapping'. These task states allow for a better view into
current moment. These tasks can be generic, such as `spawning`, or specific,
such as `block_device_mapping`. These task states allow for a better view into
what a server is doing.
Server creation
@ -102,24 +102,28 @@ Server creation
Status Transition:
``BUILD``
- ``BUILD``
``ACTIVE``
.. todo:: Add more details.
``ERROR`` (on error)
- ``ACTIVE``
When you create a server, the operation asynchronously provisions a new
server. The progress of this operation depends on several factors
including location of the requested image, network I/O, host load, and
the selected flavor. The progress of the request can be checked by
performing a **GET** on /servers/*``id``*, which returns a progress
attribute (from 0% to 100% complete). The full URL to the newly created
server is returned through the ``Location`` header and is available as a
``self`` and ``bookmark`` link in the server representation. Note that
when creating a server, only the server ID, its links, and the
administrative password are guaranteed to be returned in the request.
You can retrieve additional attributes by performing subsequent **GET**
operations on the server.
.. todo:: Add more details.
- ``ERROR`` (on error)
When you create a server, the operation asynchronously provisions a new
server. The progress of this operation depends on several factors
including location of the requested image, network I/O, host load, and
the selected flavor. The progress of the request can be checked by
performing a **GET** on /servers/*{server_id}*, which returns a progress
attribute (from 0% to 100% complete). The full URL to the newly created
server is returned through the ``Location`` header and is available as a
``self`` and ``bookmark`` link in the server representation. Note that
when creating a server, only the server ID, its links, and the
administrative password are guaranteed to be returned in the request.
You can retrieve additional attributes by performing subsequent **GET**
operations on the server.
Server query
~~~~~~~~~~~~
@ -144,31 +148,33 @@ For different user roles, the user has different query options set:
the query options are different from the attribute naming in the servers API
response.
.. code::
Precondition:
there are 2 servers existing in cloud with following info:
Precondition: there are 2 servers existing in cloud with following info::
"servers": [
{
"name": "t1",
"locked": "true",
...
},
{
"name": "t2",
"locked": "false",
...
}
]
{
"servers": [
{
"name": "t1",
"locked": "true",
...
},
{
"name": "t2",
"locked": "false",
...
}
]
}
**Example: General user query server with administrator only options**
Request with non-administrator context: ``GET /servers/detail?locked=1``
**Example: General user query server with administrator only options**
Note that ``locked`` is returned through API layer starting from
microversion 2.9.
Request with non-administrator context:
GET /servers/detail?locked=1
Note that 'locked' is not returned through API layer
Response::
Response:
{
"servers": [
{
@ -182,12 +188,12 @@ For different user roles, the user has different query options set:
]
}
**Example: Administrator query server with administrator only options**
**Example: Administrator query server with administrator only options**
Request with administrator context:
GET /servers/detail?locked=1
Request with administrator context: ``GET /servers/detail?locked=1``
Response::
Response:
{
"servers": [
{
@ -213,14 +219,13 @@ There are also some special query options:
- ``all_tenants`` is an administrator query option, which allows the
administrator to query the servers in any tenant.
.. code::
**Example: User query server with special keys changes-since or changes-before**
**Example: User query server with special keys changes-since or changes-before**
Request: ``GET /servers/detail``
Precondition:
GET /servers/detail
Response::
Response:
{
"servers": [
{
@ -236,9 +241,10 @@ There are also some special query options:
]
}
GET /servers/detail?changes-since='2015-12-16T15:55:52Z'
Request: ``GET /servers/detail?changes-since='2015-12-16T15:55:52Z'``
Response::
Response:
{
{
"name": "t2",
@ -247,9 +253,10 @@ There are also some special query options:
}
}
GET /servers/detail?changes-before='2015-12-16T15:55:52Z'
Request: ``GET /servers/detail?changes-before='2015-12-16T15:55:52Z'``
Response::
Response:
{
{
"name": "t1",
@ -258,9 +265,11 @@ There are also some special query options:
}
}
GET /servers/detail?changes-since='2015-12-10T15:55:52Z'&changes-before='2015-12-28T15:55:52Z'
Request:
``GET /servers/detail?changes-since='2015-12-10T15:55:52Z'&changes-before='2015-12-28T15:55:52Z'``
Response::
Response:
{
"servers": [
{
@ -279,15 +288,11 @@ There are also some special query options:
There are two kinds of matching in query options: Exact matching and
regex matching.
.. code::
**Example: User query server using exact matching on host**
**Example: User query server using exact matching on host**
Precondition:
Request with administrator context:
GET /servers/detail
Request with administrator context: ``GET /servers/detail``
Response:
Response::
{
"servers": [
@ -304,10 +309,9 @@ regex matching.
]
}
Request with administrator context:
GET /servers/detail?host=devstack
Request with administrator context: ``GET /servers/detail?host=devstack``
Response:
Response::
{
"servers": [
@ -319,13 +323,11 @@ regex matching.
]
}
**Example: Query server using regex matching on name**
**Example: Query server using regex matching on name**
Precondition:
Request with administrator context:
GET /servers/detail
Request with administrator context: ``GET /servers/detail``
Response:
Response::
{
"servers": [
@ -348,10 +350,9 @@ regex matching.
]
}
Request with administrator context:
GET /servers/detail?name=t1
Request with administrator context: ``GET /servers/detail?name=t1``
Response:
Response::
{
"servers": [
@ -370,14 +371,12 @@ regex matching.
]
}
**Example: User query server using exact matching on host and
regex matching on name**
**Example: User query server using exact matching on host and regex
matching on name**
Precondition:
Request with administrator context:
GET /servers/detail
Request with administrator context: ``GET /servers/detail``
Response:
Response::
{
"servers": [
@ -399,10 +398,10 @@ regex matching.
]
}
Request with administrator context:
GET /servers/detail?host=devstack1&name=test
Request with administrator context:
``GET /servers/detail?host=devstack1&name=test``
Response:
Response::
{
"servers": [
@ -414,16 +413,10 @@ regex matching.
]
}
"name": "t2",
"updated": "2015-12-17T15:55:52Z"
...
}
]
}
Request: ``GET /servers/detail?changes-since='2015-12-16T15:55:52Z'``
GET /servers/detail?changes-since='2015-12-16T15:55:52Z'
Response::
Response:
{
{
"name": "t2",
@ -635,7 +628,7 @@ limit.
Block Device Mapping
~~~~~~~~~~~~~~~~~~~~
TODO: Add some description about BDM.
.. todo:: Add some description about BDM.
Scheduler Hints
~~~~~~~~~~~~~~~
@ -706,7 +699,7 @@ assigned at creation time.
**Example: Create server with access IP: JSON request**
.. code::
.. code-block:: json
{
"server": {
@ -724,7 +717,7 @@ assigned at creation time.
**Example: Create server with multiple access IPs: JSON request**
.. code::
.. code-block:: json
{
"server": {
@ -803,7 +796,7 @@ a cloud:
This process can be repeated until the whole cloud has been updated,
usually using a pool of empty hosts instead of just one.
- **Resource Optimization**
- **Resource Optimization**
To reduce energy usage, some cloud operators will try and move
servers so they fit into the minimum number of hosts, allowing

16
api-guide/source/users.rst

@ -27,7 +27,7 @@ Keystone middleware is used to authenticate users and identify their roles.
The Compute API uses these roles, along with oslo.policy, to decide
what the user is authorized to do.
TODO - link to compute admin guide for details.
.. todo:: link to compute admin guide for details.
Personas used in this guide
===========================
@ -47,11 +47,15 @@ cloud administrator permissions, such as a read-only role that is able to view
a lists of servers for a specific tenant but is not able to perform any
actions on any of them.
Note: this is not attempting to be an exhaustive set of personas that consider
various facets of the different users but instead aims to be a minimal set of
users such that we use a consistent terminology throughout this document.
.. note::
TODO - could assign names to these users, or similar, to make it more "real".
This is not attempting to be an exhaustive set of personas that consider
various facets of the different users but instead aims to be a minimal set of
users such that we use a consistent terminology throughout this document.
.. todo::
could assign names to these users, or similar, to make it more "real".
Discovering Policy
==================
@ -59,4 +63,4 @@ Discovering Policy
An API to discover what actions you are authorized to perform is still a work
in progress. Currently this reported by a HTTP 403 error.
TODO - link to the doc on errors.
.. todo:: link to the doc on errors.

12
api-guide/source/versions.rst

@ -4,8 +4,8 @@ Versions
The OpenStack Compute API uses both a URI and a MIME type versioning
scheme. In the URI scheme, the first element of the path contains the
target version identifier (e.g. https://servers.api.openstack.org/
v2.1/...). The MIME type versioning scheme uses HTTP content negotiation
target version identifier (e.g. `https://servers.api.openstack.org/
v2.1/`...). The MIME type versioning scheme uses HTTP content negotiation
where the ``Accept`` or ``Content-Type`` headers contains a MIME type
that identifies the version (application/vnd.openstack.compute.v2.1+json).
A version MIME type is always linked to a base MIME type, such as
@ -37,7 +37,7 @@ Permanent Links
The MIME type versioning approach allows for creating of permanent
links, because the version scheme is not specified in the URI path:
https://api.servers.openstack.org/224532/servers/123.
`https://api.servers.openstack.org/224532/servers/123`.
If a request is made without a version specified in the URI or via HTTP
headers, then a multiple-choices response (300) follows that provides
@ -99,12 +99,12 @@ everything following that truncated) returned from the authentication system.
You can also obtain additional information about a specific version by
performing a **GET** on the base version URL (such as,
``https://servers.api.openstack.org/v2.1/``). Version request URLs must
always end with a trailing slash (``/``). If you omit the slash, the
`https://servers.api.openstack.org/v2.1/`). Version request URLs must
always end with a trailing slash (`/`). If you omit the slash, the
server might respond with a 302 redirection request.
For examples of the list versions and get version details requests and
responses, see `*API versions*
responses, see `API versions
<https://developer.openstack.org/api-ref/compute/#api-versions>`__.
The detailed version response contains pointers to both a human-readable

Loading…
Cancel
Save