openstack
/
neutron-specs
Code Issues Proposed changes

Removed networking_general_api_information.rst 

This information now lives in api-ref.

Change-Id: I31ad535ba3b1b15e421f08e94c1cf80eb0edfd1b
Depends-On: Ic0c2348d7db941deaec6e1d110954fe5893c2265
This commit is contained in:
Ihar Hrachyshka 2016-08-27 21:07:04 +00:00
parent 79289e17fe
commit 13a5852771
1 changed files with 0 additions and 533 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

533
misc/api/networking_general_api_information.rst
View File

@ -1,533 +0,0 @@
=======================================
Networking API v2.0 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&amp;marker=71c1e68c-171a-4aa2-aca5-50ea153a3718" rel="next"/>
<atom:link href="http://127.0.0.1:9696/v2.0/networks.xml?limit=2&amp;marker=396f12f8-521e-4b91-8e21-2e003500433a&amp;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&amp;marker=b3680498-03da-4691-896f-ef9ee1d856a7&amp;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.