Move valuable API info from neutron-specs repo
This information is stored (unlinked) in neutron-specs repo under misc/api/networking_general_api_information.rst This patch just moves the contents into api-ref, where they seem to belong. Note that the contents are not current in some parts. For example, it is said there XML format of requests is still supported, which is not true for quite a while. This contents will be cleaned up in follow up patches. For now, I keep the text intact to ease reviewer's life. Adding two documentation bugs to be closed by the patch because the information missing in api-ref is already included in the bits copied by this patch. Closes-Bug: #1609934 Closes-Bug: #1609932 Change-Id: Ic0c2348d7db941deaec6e1d110954fe5893c2265
This commit is contained in:
Ihar Hrachyshka
parent
ba7dee0bfd
commit
adef52edff
@ -11,3 +11,496 @@ API guide
|
||||
This section introduces readers to OpenStack Networking (v2) API, providers
|
||||
guidelines on how to use it, and describes common features available to users
|
||||
throughout all Networking APIs.
|
||||
|
||||
General information
|
||||
===================
|
||||
|
||||
The Networking API v2.0 is a ReSTful HTTP service that uses all aspects of the
|
||||
HTTP protocol including methods, URIs, media types, response codes, and so on.
|
||||
Providers can use existing features of the protocol including caching,
|
||||
persistent connections, and content compression. For example, providers who
|
||||
employ a caching layer can respond with a 203 code instead of a 200 code when a
|
||||
request is served from the cache. Additionally, providers can offer support
|
||||
for conditional **GET** requests by using ETags, or they may send a redirect in
|
||||
response to a **GET** request. Create clients so that these differences are
|
||||
accounted for.
|
||||
|
||||
Authentication and authorization
|
||||
================================
|
||||
|
||||
The Networking API v2.0 uses the `OpenStack Identity service
|
||||
<https://docs.openstack.org/developer/keystone>`_ as the default authentication
|
||||
service. When Keystone is enabled, users that submit requests to the OpenStack
|
||||
Networking 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 ``tenant_id`` attribute is not required in create
|
||||
requests because the tenant ID is derived from the authentication token.
|
||||
|
||||
The default authorization settings allow only administrative users to create
|
||||
resources on behalf of a different tenant.
|
||||
|
||||
OpenStack Networking uses information received from Keystone to authorize user
|
||||
requests. OpenStack 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 OpenStack Networking might vary
|
||||
from deployment to deployment.
|
||||
|
||||
Request and response formats
|
||||
============================
|
||||
|
||||
The Networking API v2.0 supports both JSON and XML data serialization request
|
||||
and response formats.
|
||||
|
||||
Request format
|
||||
--------------
|
||||
|
||||
Use the ``Content-Type`` request header to specify the request format. This
|
||||
header is required for operations that have a request body.
|
||||
|
||||
The syntax for the ``Content-Type`` header is:
|
||||
|
||||
.. code::
|
||||
|
||||
Content-Type: application/FORMAT
|
||||
|
||||
Where *FORMAT* is either ``json`` or ``xml``.
|
||||
|
||||
Response format
|
||||
---------------
|
||||
|
||||
Use one of the following methods to specify the response format:
|
||||
|
||||
``Accept`` header
|
||||
The syntax for the ``Accept`` header is:
|
||||
|
||||
.. code::
|
||||
|
||||
Accept: application/FORMAT
|
||||
|
||||
Where *FORMAT* is either ``json`` or ``xml``. The default format is
|
||||
``json``.
|
||||
|
||||
Query extension
|
||||
Add an ``.xml`` or ``.json`` extension to the request URI. For example, the
|
||||
``.xml`` extension in the following list networks URI request specifies
|
||||
that the response body is to be returned in XML format:
|
||||
|
||||
**GET** *publicURL*/networks.xml
|
||||
|
||||
If you do not specify a response format, JSON is the default.
|
||||
|
||||
If the ``Accept`` header and the query extension specify conflicting formats,
|
||||
the format specified in the query extension takes precedence. For example, if
|
||||
the query extension is ``.xml`` and the ``Accept`` header specifies
|
||||
``application/json``, the response is returned in XML format.
|
||||
|
||||
You can serialize a response in a different format from the request format.
|
||||
|
||||
Filtering and column selection
|
||||
==============================
|
||||
|
||||
The Networking 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 networks named ``foobar``:
|
||||
|
||||
.. code::
|
||||
|
||||
GET /v2.0/networks?name=foobar
|
||||
|
||||
When you specify multiple filters, the Networking API v2.0 returns only objects
|
||||
that meet all filtering criteria. The operation applies an AND condition among
|
||||
the filters.
|
||||
|
||||
Note
|
||||
----
|
||||
|
||||
OpenStack Networking 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, OpenStack Networking returns all attributes for any show or list
|
||||
call. The Networking 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 Networking API v2.0.
|
||||
|
||||
For example, the following request returns only ``id`` and ``name`` for each
|
||||
network:
|
||||
|
||||
.. code::
|
||||
|
||||
GET /v2.0/networks.json?fields=id&fields=name
|
||||
|
||||
Synchronous versus asynchronous plug-in behavior
|
||||
================================================
|
||||
|
||||
The Networking API v2.0 presents a logical model of network connectivity
|
||||
consisting of networks, ports, and subnets. It is up to the OpenStack
|
||||
Networking plug-in to communicate with the underlying infrastructure to ensure
|
||||
packet forwarding 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 switching 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 attachment
|
||||
for a port, there is no guarantee that packets sent by the interface named in
|
||||
the attachment are forwarded immediately when the HTTP call returns. However,
|
||||
it is guaranteed that a subsequent HTTP **GET** request to view the attachment
|
||||
on that port returns the new attachment value.
|
||||
|
||||
You can use the ``status`` attribute with the network and port resources to
|
||||
determine whether the OpenStack Networking plug-in has successfully completed
|
||||
the configuration of the resource.
|
||||
|
||||
Bulk-create
|
||||
===========
|
||||
|
||||
The Networking API v2.0 enables you to create several objects of the same type
|
||||
in the same API request. Bulk create operations use exactly the same API syntax
|
||||
as single create operations except that you specify a list of objects rather
|
||||
than a single object in the request body.
|
||||
|
||||
Bulk operations are always performed atomically, meaning that either all or
|
||||
none of the objects in the request body are created. If a particular plug-in
|
||||
does not support atomic operations, the Networking API v2.0 emulates the atomic
|
||||
behavior so that users can expect the same behavior regardless of the
|
||||
particular plug-in running in the background.
|
||||
|
||||
OpenStack Networking might be deployed without support for bulk operations and
|
||||
when the client attempts a bulk create operation, a 400 Bad request error is
|
||||
returned.
|
||||
|
||||
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://127.0.0.1:9696/v2.0/networks.json?limit=2
|
||||
|
||||
Pagination is an optional feature of OpenStack Networking API, and it might be
|
||||
disabled. If pagination is disabled, the pagination parameters will be ignored
|
||||
and return all the items.
|
||||
|
||||
If a particular plug-in does not support pagination operations, and pagination
|
||||
is enabled, the Networking 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.
|
||||
|
||||
To determine if pagination is supported, a user can check whether the
|
||||
'pagination' extension API is available.
|
||||
|
||||
**Example Network collection, first page: JSON request**
|
||||
|
||||
.. code::
|
||||
|
||||
GET /v2.0/networks.json?limit=2 HTTP/1.1
|
||||
Host: 127.0.0.1:9696
|
||||
Content-Type: application/json
|
||||
Accept: application/json
|
||||
|
||||
|
||||
|
||||
**Example Network collection, first page: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"networks": [
|
||||
{
|
||||
"admin_state_up": true,
|
||||
"id": "396f12f8-521e-4b91-8e21-2e003500433a",
|
||||
"name": "net3",
|
||||
"provider:network_type": "vlan",
|
||||
"provider:physical_network": "physnet1",
|
||||
"provider:segmentation_id": 1002,
|
||||
"router:external": false,
|
||||
"shared": false,
|
||||
"status": "ACTIVE",
|
||||
"subnets": [],
|
||||
"tenant_id": "20bd52ff3e1b40039c312395b04683cf"
|
||||
},
|
||||
{
|
||||
"admin_state_up": true,
|
||||
"id": "71c1e68c-171a-4aa2-aca5-50ea153a3718",
|
||||
"name": "net2",
|
||||
"provider:network_type": "vlan",
|
||||
"provider:physical_network": "physnet1",
|
||||
"provider:segmentation_id": 1001,
|
||||
"router:external": false,
|
||||
"shared": false,
|
||||
"status": "ACTIVE",
|
||||
"subnets": [],
|
||||
"tenant_id": "20bd52ff3e1b40039c312395b04683cf"
|
||||
}
|
||||
],
|
||||
"networks_links": [
|
||||
{
|
||||
"href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718",
|
||||
"rel": "next"
|
||||
},
|
||||
{
|
||||
"href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=396f12f8-521e-4b91-8e21-2e003500433a&page_reverse=True",
|
||||
"rel": "previous"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
|
||||
**Example Network collection, first page: XML request**
|
||||
|
||||
.. code::
|
||||
|
||||
GET /v2.0/networks.xml?limit=2 HTTP/1.1
|
||||
Host: 127.0.0.1:9696
|
||||
Content-Type: application/xml
|
||||
Accept: application/xml
|
||||
|
||||
|
||||
|
||||
**Example Network collection, first page: XML response**
|
||||
|
||||
.. code::
|
||||
|
||||
<?xml version="1.0" ?>
|
||||
<networks xmlns="http://openstack.org/neutron/api/v2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0" xmlns:neutron="http://openstack.org/neutron/api/v2.0" xmlns:router="http://docs.openstack.org/ext/neutron/router/api/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|
||||
<network>
|
||||
<status>ACTIVE</status>
|
||||
<subnets neutron:type="list"/>
|
||||
<name>net3</name>
|
||||
<provider:physical_network>physnet1</provider:physical_network>
|
||||
<admin_state_up neutron:type="bool">True</admin_state_up>
|
||||
<tenant_id>20bd52ff3e1b40039c312395b04683cf</tenant_id>
|
||||
<provider:network_type>vlan</provider:network_type>
|
||||
<router:external neutron:type="bool">False</router:external>
|
||||
<shared neutron:type="bool">False</shared>
|
||||
<id>396f12f8-521e-4b91-8e21-2e003500433a</id>
|
||||
<provider:segmentation_id neutron:type="long">1002</provider:segmentation_id>
|
||||
</network>
|
||||
<network>
|
||||
<status>ACTIVE</status>
|
||||
<subnets neutron:type="list"/>
|
||||
<name>net2</name>
|
||||
<provider:physical_network>physnet1</provider:physical_network>
|
||||
<admin_state_up neutron:type="bool">True</admin_state_up>
|
||||
<tenant_id>20bd52ff3e1b40039c312395b04683cf</tenant_id>
|
||||
<provider:network_type>vlan</provider:network_type>
|
||||
<router:external neutron:type="bool">False</router:external>
|
||||
<shared neutron:type="bool">False</shared>
|
||||
<id>71c1e68c-171a-4aa2-aca5-50ea153a3718</id>
|
||||
<provider:segmentation_id neutron:type="long">1001</provider:segmentation_id>
|
||||
</network>
|
||||
<atom:link href="http://127.0.0.1:9696/v2.0/networks.xml?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718" rel="next"/>
|
||||
<atom:link href="http://127.0.0.1:9696/v2.0/networks.xml?limit=2&marker=396f12f8-521e-4b91-8e21-2e003500433a&page_reverse=True" rel="previous"/>
|
||||
</networks>
|
||||
|
||||
|
||||
|
||||
The last page won't show the "next" links
|
||||
|
||||
**Example Network collection, last page: JSON request**
|
||||
|
||||
.. code::
|
||||
|
||||
GET /v2.0/networks.json?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718 HTTP/1.1
|
||||
Host: 127.0.0.1:9696
|
||||
Content-Type: application/json
|
||||
Accept: application/json
|
||||
|
||||
|
||||
|
||||
**Example Network collection, last page: JSON response**
|
||||
|
||||
.. code::
|
||||
|
||||
{
|
||||
"networks": [
|
||||
{
|
||||
"admin_state_up": true,
|
||||
"id": "b3680498-03da-4691-896f-ef9ee1d856a7",
|
||||
"name": "net1",
|
||||
"provider:network_type": "vlan",
|
||||
"provider:physical_network": "physnet1",
|
||||
"provider:segmentation_id": 1000,
|
||||
"router:external": false,
|
||||
"shared": false,
|
||||
"status": "ACTIVE",
|
||||
"subnets": [],
|
||||
"tenant_id": "c05140b3dc7c4555afff9fab6b58edc2"
|
||||
}
|
||||
],
|
||||
"networks_links": [
|
||||
{
|
||||
"href": "http://127.0.0.1:9696/v2.0/networks.json?limit=2&marker=b3680498-03da-4691-896f-ef9ee1d856a7&page_reverse=True",
|
||||
"rel": "previous"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
|
||||
**Example Network collection, last page: XML request**
|
||||
|
||||
.. code::
|
||||
|
||||
GET /v2.0/networks.xml?limit=2&marker=71c1e68c-171a-4aa2-aca5-50ea153a3718 HTTP/1.1
|
||||
Host: 127.0.0.1:9696
|
||||
Content-Type: application/xml
|
||||
Accept: application/xml
|
||||
|
||||
|
||||
|
||||
**Example Network collection, last page: XML response**
|
||||
|
||||
.. code::
|
||||
|
||||
<?xml version="1.0" ?>
|
||||
<networks xmlns="http://openstack.org/neutron/api/v2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:provider="http://docs.openstack.org/ext/provider/api/v1.0" xmlns:neutron="http://openstack.org/neutron/api/v2.0" xmlns:router="http://docs.openstack.org/ext/neutron/router/api/v1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
|
||||
<network>
|
||||
<status>ACTIVE</status>
|
||||
<subnets neutron:type="list"/>
|
||||
<name>net1</name>
|
||||
<provider:physical_network>physnet1</provider:physical_network>
|
||||
<admin_state_up neutron:type="bool">True</admin_state_up>
|
||||
<tenant_id>c05140b3dc7c4555afff9fab6b58edc2</tenant_id>
|
||||
<provider:network_type>vlan</provider:network_type>
|
||||
<router:external neutron:type="bool">False</router:external>
|
||||
<shared neutron:type="bool">False</shared>
|
||||
<id>b3680498-03da-4691-896f-ef9ee1d856a7</id>
|
||||
<provider:segmentation_id neutron:type="long">1000</provider:segmentation_id>
|
||||
</network>
|
||||
<atom:link href="http://127.0.0.1:9696/v2.0/networks.xml?limit=2&marker=b3680498-03da-4691-896f-ef9ee1d856a7&page_reverse=True" rel="previous"/>
|
||||
</networks>
|
||||
|
||||
|
||||
|
||||
Sorting
|
||||
=======
|
||||
|
||||
You can 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).
|
||||
|
||||
Sorting is optional feature of OpenStack Networking API, and it might be
|
||||
disabled. If sorting is disabled, the sorting parameters are ignored.
|
||||
|
||||
If a particular plug-in does not support sorting operations and sorting is
|
||||
enabled, the Networking 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.
|
||||
|
||||
To determine if sorting is supported, a user can check whether the 'sorting'
|
||||
extension API is available.
|
||||
|
||||
Extensions
|
||||
==========
|
||||
|
||||
The Networking API v2.0 is extensible.
|
||||
|
||||
The purpose of Networking API v2.0 extensions is to:
|
||||
|
||||
- Introduce new features in the API without requiring a version change.
|
||||
|
||||
- Introduce vendor-specific niche functionality.
|
||||
|
||||
- Act as a proving ground for experimental functionalities that might be
|
||||
included in a future version of the API.
|
||||
|
||||
To programmatically determine which extensions are available, issue a **GET**
|
||||
request on the **v2.0/extensions** URI.
|
||||
|
||||
To query extensions individually by unique alias, issue a **GET** request on
|
||||
the ``/v2.0/extensions/*alias_name*`` URI. Use this method to easily
|
||||
determine if an extension is available. If the extension is not available, a
|
||||
404 Not Found response is returned.
|
||||
|
||||
You can extend existing core API resources with new actions or extra
|
||||
attributes. Also, you can add new resources as extensions. Extensions usually
|
||||
have tags that prevent conflicts with other extensions that define attributes
|
||||
or resources with the same names, and with core resources and attributes.
|
||||
Because an extension might not be supported by all plug-ins, the availability
|
||||
of an extension varies with deployments and the specific plug-in in use.
|
||||
|
||||
|
||||
Faults
|
||||
======
|
||||
|
||||
The Networking API v2.0 returns an error response if a failure occurs while
|
||||
processing a request. OpenStack Networking uses only standard HTTP error codes.
|
||||
4\ *nn* errors indicate problems in the particular request being sent from
|
||||
the client.
|
||||
|
||||
+-------+--------------------------------------------------------------+
|
||||
| Error | 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) |
|
||||
+-------+--------------------------------------------------------------+
|
||||
| 404 | Not Found |
|
||||
| | Non existent URI |
|
||||
| | Resource not found |
|
||||
+-------+--------------------------------------------------------------+
|
||||
| 409 | Conflict |
|
||||
| | Port configured on network |
|
||||
| | IP allocated on subnet |
|
||||
| | Conflicting IP allocation pools for subnet |
|
||||
+-------+--------------------------------------------------------------+
|
||||
| 500 | Internal server error |
|
||||
| | Internal OpenStack Networking error |
|
||||
+-------+--------------------------------------------------------------+
|
||||
| 503 | Service unavailable |
|
||||
| | Failure in Mac address generation |
|
||||
+-------+--------------------------------------------------------------+
|
||||
|
||||
Users submitting requests to the Networking API v2.0 might also receive the
|
||||
following errors:
|
||||
|
||||
- 401 Unauthorized - If invalid credentials are provided.
|
||||
|
||||
- 403 Forbidden - If the user cannot access a specific resource or perform the
|
||||
requested operation.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user