Merge "Improve formats of the Compute API guide"
This commit is contained in:
commit
6e8a69daf1
|
@ -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'
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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,
|
||||
|
|
|
@ -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.
|
||||
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.
|
||||
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.
|
||||
|
||||
|
|
|
@ -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)**
|
||||
|
|
|
@ -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:
|
||||
|
||||
|
|
|
@ -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**
|
||||
**Example: General user query server with administrator only options**
|
||||
|
||||
Request with non-administrator context:
|
||||
GET /servers/detail?locked=1
|
||||
Note that 'locked' is not returned through API layer
|
||||
Request with non-administrator context: ``GET /servers/detail?locked=1``
|
||||
|
||||
Note that ``locked`` is returned through API layer starting from
|
||||
microversion 2.9.
|
||||
|
||||
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**
|
||||
|
||||
Precondition:
|
||||
GET /servers/detail
|
||||
Request: ``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**
|
||||
Request with administrator context: ``GET /servers/detail``
|
||||
|
||||
Precondition:
|
||||
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
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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…
Reference in New Issue