502 lines
19 KiB
ReStructuredText
502 lines
19 KiB
ReStructuredText
.. -*- rst -*-
|
||
.. needs:method_verification
|
||
.. needs:parameter_verification
|
||
.. needs:example_verification
|
||
.. needs:body_verification
|
||
|
||
=========
|
||
API guide
|
||
=========
|
||
|
||
This section introduces readers to OpenStack Networking (v2) API, provides
|
||
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/keystone/latest/>`_ 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 ``project_id`` attribute is not required in create
|
||
requests because the project ID is derived from the authentication token.
|
||
|
||
NOTE: Currently the Networking API accepts the deprecated ``tenant_id``
|
||
attribute for the project ID for backward compatibility.
|
||
|
||
The default authorization settings allow only administrative users to create
|
||
resources on behalf of a different project.
|
||
|
||
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 JSON data serialization request and response
|
||
formats only.
|
||
|
||
Request format
|
||
--------------
|
||
|
||
The Networking API v2.0 only accepts requests with the JSON data serialization
|
||
format. The ``Content-Type`` header is ignored.
|
||
|
||
Tenant and project attributes in requests
|
||
-----------------------------------------
|
||
|
||
Starting with the Newton release of the Networking service, the Networking API
|
||
accepts the ``project_id`` attribute in addition to the ``tenant_id`` attribute
|
||
in requests. The ``tenant_id`` attribute is accepted for backward compatibility.
|
||
If both the ``project_id`` and the ``tenant_id`` attribute are provided in the
|
||
same request, their values must be identical.
|
||
|
||
To determine whether a Networking API v2.0 endpoint supports the ``project_id``
|
||
attribute in requests, check that the ``project-id`` API extension is enabled
|
||
(see Extensions_).
|
||
|
||
|
||
Response format
|
||
---------------
|
||
|
||
The Networking API v2.0 always responds with the JSON data serialization
|
||
format. The ``Accept`` header is ignored.
|
||
|
||
Query extension
|
||
A ``.json`` extension can be added to the request URI. For example, the
|
||
``.json`` extension in the following requests are equivalent:
|
||
|
||
- GET *publicURL*/networks
|
||
|
||
- GET *publicURL*/networks.json
|
||
|
||
Tenant and project attributes in responses
|
||
------------------------------------------
|
||
|
||
Starting with the Newton release of the Networking service, the Networking API
|
||
returns a ``project_id`` attribute in responses, while still returning a
|
||
``tenant_id`` attribute for backward compatibility. The values will always be
|
||
identical.
|
||
|
||
To determine whether a Networking API v2.0 endpoint returns the ``project_id``
|
||
attribute in responses, check that the ``project-id`` API extension is enabled
|
||
(see Extensions_).
|
||
|
||
|
||
.. _filtering:
|
||
|
||
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 using different fields, the Networking API
|
||
v2.0 returns only objects that meet all filtering criteria. The operation
|
||
applies an AND condition among different filter fields.
|
||
|
||
OpenStack Networking offers an OR mechanism for filters by repeating the field
|
||
with the different OR criteria. For example, to find all networks named
|
||
``foobar`` OR ``bizbaz``:
|
||
|
||
.. code::
|
||
|
||
GET /v2.0/networks?name=foobar&name=bizbaz
|
||
|
||
|
||
ORs and ANDs can be combined. For example, if you want all networks with
|
||
admin_state_up=True and shared=True and named ``foobar`` or ``bizbaz``:
|
||
|
||
.. code::
|
||
|
||
GET /v2.0/networks?name=foobar&name=bizbaz&admin_state_up=True&shared=True
|
||
|
||
List of resources is supported in GET requests. For example, if you want the
|
||
information of two specific ports that ``id`` is ``port_id_A`` or ``port_id_B``:
|
||
|
||
.. code::
|
||
|
||
GET /v2.0/ports?id=port_id_A&id=port_id_B
|
||
|
||
It treats ID filters as list and return ports with those 2 IDs.
|
||
|
||
Starting from Rocky release, the Networking API might support filtering
|
||
attributes with empty value. For example, the request below lists all ports
|
||
that have ``device_id`` attribute with empty value (which are unbound ports).
|
||
|
||
.. code::
|
||
|
||
GET /v2.0/networks?device_id=
|
||
|
||
To determine if this feature is supported, a user can check whether the
|
||
``empty-string-filtering`` extension API is available.
|
||
|
||
Starting from Rocky release, the Networking API will perform validation
|
||
on filtering attributes if the API extension ``filter-validation`` is
|
||
available. If an API request contains an unknown or unsupported
|
||
parameter, the server will return a ``400`` response instead of silently
|
||
ignoring the invalid input.
|
||
|
||
Note
|
||
----
|
||
|
||
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"
|
||
"project_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"
|
||
"project_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"
|
||
}
|
||
]
|
||
}
|
||
|
||
|
||
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"
|
||
"project_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"
|
||
}
|
||
]
|
||
}
|
||
|
||
|
||
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.
|
||
|
||
Starting from Rocky release, the Networking API performs validation on
|
||
sorting attributes if the API extension ``sort-key-validation`` is available.
|
||
If an API request contains an unknown or unsupported sort key,
|
||
the server will return a ``400`` response instead of silently ignoring
|
||
the invalid input.
|
||
|
||
|
||
.. _Extensions:
|
||
|
||
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.
|
||
``4nn`` 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 |
|
||
+-------+--------------------------------------------------------------+
|
||
|``412``| Precondition failed |
|
||
| | The revision number is mismatched |
|
||
+-------+--------------------------------------------------------------+
|
||
|``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.
|
||
|
||
|
||
Revisions
|
||
=========
|
||
|
||
The ``Resource revision numbers`` extension (``standard-attr-revisions``) adds
|
||
the ``revision_number`` attribute to all API resources that support standard
|
||
attributes. This includes networks, ports, subnets, subnet pools, floating IPs,
|
||
routers, logs, security groups/rules, network segments, QoS policies and trunks.
|
||
As you'd expect, the ``revision_number`` indicates the number of updates a
|
||
particular resource has undergone and is read-only.
|
||
|
||
In addition, the ``If-Match constraints based on revision_number`` extension
|
||
(``revision-if-match``) allows API consumers to leverage the ``If-Match`` HTTP
|
||
header to conditionally update/delete a resource when the HTTP ``If-Match``
|
||
header matches the ``revision_number`` of the said resource.
|
||
|
||
If the HTTP ``If-Match`` header doesn't match the ``revision_number`` of the
|
||
resource, users will receive the following errors:
|
||
|
||
- ``412 Precondition failed`` - Update/Delete the target resource has been
|
||
denied due to the mismatch of revision number.
|