2012 lines
91 KiB
XML
2012 lines
91 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
||
<!DOCTYPE book [
|
||
<!-- Some useful entities borrowed from HTML -->
|
||
<!ENTITY ndash "–">
|
||
<!ENTITY mdash "—">
|
||
<!ENTITY hellip "…">
|
||
<!ENTITY plusmn "±">
|
||
|
||
<!-- Useful for describing APIs -->
|
||
<!ENTITY GET '<command xmlns="http://docbook.org/ns/docbook">GET</command>'>
|
||
<!ENTITY PUT '<command xmlns="http://docbook.org/ns/docbook">PUT</command>'>
|
||
<!ENTITY POST '<command xmlns="http://docbook.org/ns/docbook">POST</command>'>
|
||
<!ENTITY DELETE '<command xmlns="http://docbook.org/ns/docbook">DELETE</command>'>
|
||
|
||
<!ENTITY CHECK '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||
<imageobject role="fo">
|
||
<imagedata fileref="figures/Check_mark_23x20_02.svg"
|
||
format="SVG" scale="60"/>
|
||
</imageobject>
|
||
<imageobject role="html">
|
||
<imagedata fileref="../figures/Check_mark_23x20_02.png"
|
||
format="PNG" />
|
||
</imageobject>
|
||
</inlinemediaobject>'>
|
||
|
||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||
<imageobject role="fo">
|
||
<imagedata fileref="figures/Arrow_east.svg"
|
||
format="SVG" scale="60"/>
|
||
</imageobject>
|
||
<imageobject role="html">
|
||
<imagedata fileref="../figures/Arrow_east.png"
|
||
format="PNG" />
|
||
</imageobject>
|
||
</inlinemediaobject>'>
|
||
]>
|
||
<book xmlns="http://docbook.org/ns/docbook"
|
||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||
xmlns:svg="http://www.w3.org/2000/svg"
|
||
xmlns:m="http://www.w3.org/1998/Math/MathML"
|
||
xmlns:html="http://www.w3.org/1999/xhtml"
|
||
xmlns:db="http://docbook.org/ns/docbook"
|
||
version="5.0" status="final"
|
||
xml:id="Quantum-api-spec">
|
||
<title>Quantum API Guide (1.0)</title>
|
||
<titleabbrev>Quantum API 1.0</titleabbrev>
|
||
<info>
|
||
<author>
|
||
<personname>
|
||
<firstname/>
|
||
<surname/>
|
||
</personname>
|
||
</author>
|
||
<copyright>
|
||
<year>2011</year>
|
||
<holder>OpenStack</holder>
|
||
</copyright>
|
||
<releaseinfo>Quantum API v1.0</releaseinfo>
|
||
<productname>OpenStack Quantum (virtual network service)</productname>
|
||
<pubdate>2011-09-22</pubdate>
|
||
<legalnotice role="apache2">
|
||
<annotation>
|
||
<remark>Copyright details are filled in by the template.</remark>
|
||
</annotation>
|
||
</legalnotice>
|
||
<abstract>
|
||
<para>This document is intended for software developers interested in developing
|
||
applications using the OpenStack Quantum Layer-2 Networking Service
|
||
(<abbrev>API</abbrev>). </para>
|
||
</abstract>
|
||
</info>
|
||
<chapter xml:id="Overview-d1e71">
|
||
<title>Overview</title>
|
||
<para>
|
||
Quantum is a project to provide "network connectivity as a
|
||
service" between devices managed by the OpenStack compute service.
|
||
For more information on Quantum and the other network-related
|
||
projects please check the Quantum home page
|
||
(<link xlink:href="http://wiki.openstack.org/Quantum"/>)
|
||
and the NetStack home page
|
||
(<link xlink:href="http://wiki.openstack.org/Network"/>).
|
||
</para>
|
||
<para> We welcome feedback, comments, and bug reports at <link
|
||
xlink:href="http://bugs.launchpad.net/Quantum">bugs.launchpad.net/Quantum</link>.
|
||
</para>
|
||
<section xml:id="Intended_Audience-d1e85">
|
||
<title>Intended Audience</title>
|
||
<para> This Guide is intended to assist software
|
||
developers who want to develop applications using the
|
||
Quantum API. To use the information provided
|
||
here, you should first have a general understanding of the
|
||
OpenStack Quantum network service, the OpenStack compute
|
||
service (Nova), and the integration between the two.
|
||
The user should also have access to a plugin providing the
|
||
implementation for the API described in this document.
|
||
Two plugins are included in the Quantum distribution:
|
||
</para>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Openvswitch - Implementing Quantum API with Open vSwitch</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Cisco - Implementing Quantum API for Cisco UCS blades and
|
||
Nexus switches</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
You should also be familiar with:
|
||
</para>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>ReSTful web services</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>HTTP/1.1</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>JSON and/or XML data serialization formats</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
<section xml:id="Document_Change_History-d1e118">
|
||
<title>Document Change History</title>
|
||
<para>The most recent changes are described in the table below:</para>
|
||
<informaltable rules='all'>
|
||
<thead>
|
||
<tr>
|
||
<td align="center" colspan="1">Revision Date</td>
|
||
<td align="center" colspan="4">Summary of Changes</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1" align="center">September 22, 2011</td>
|
||
<td colspan="4">
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
Initial release.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Glossary">
|
||
<title>Glossary</title>
|
||
<informaltable rules='all'>
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1" align="center">Term</td>
|
||
<td colspan="4" align="center">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1" align="center">
|
||
Entity
|
||
</td>
|
||
<td colspan="4">
|
||
A generic term for any piece of hardware or
|
||
software desiring to connect to the network
|
||
services provided by Quantum. An entity may
|
||
make use of Quantum by implementing a VIF.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1" align="center" bgcolor="#4F91BD">
|
||
Layer-2 network
|
||
</td>
|
||
<td colspan="4" bgcolor="#4F91BD">
|
||
A virtual Ethernet network managed by the Quantum
|
||
service. For the time being, Quantum will manage
|
||
only Ethernet networks.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center">
|
||
Network
|
||
</td>
|
||
<td colspan="4">
|
||
A virtual network providing connectivity
|
||
between entities, i.e.: collection of virtual
|
||
ports sharing network connectivity. In the
|
||
Quantum terminology, a network is always a Layer-2
|
||
network.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center" bgcolor="#4F91BD">
|
||
Plugin
|
||
</td>
|
||
<td colspan="4" bgcolor="#4F91BD">
|
||
Software component providing the actual
|
||
implementation for Quantum APIs.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center">
|
||
Port
|
||
</td>
|
||
<td colspan="4">
|
||
A port on the virtual network switch represented
|
||
by a Quantum virtual Layer-2 network.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center" bgcolor="#4F91BD">
|
||
VIF
|
||
</td>
|
||
<td colspan="4" bgcolor="#4F91BD">
|
||
A Virtual network InterFace plugged into a port of a Quantum
|
||
network; typically a virtual network interface
|
||
belonging to a VM
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td align="center">
|
||
Attachment
|
||
</td>
|
||
<td colspan="4">
|
||
Association of an interface identifier to a logical
|
||
port, which represent 'plugging' an interface into
|
||
a port.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Theory">
|
||
<title>Theory of Operation</title>
|
||
<para>
|
||
This section presents the objects and semantics of Quantum’s
|
||
logical model.
|
||
</para><para>
|
||
Quantum abstracts the physical implementation of the network,
|
||
allowing plugins to configure and manage physical resources.
|
||
Quantum is a standalone service, in that it requires no other
|
||
project within OpenStack to function correctly.
|
||
</para><para>
|
||
Further Quantum is agnostic to the entities it allows to connect.
|
||
While we anticipate Nova instances will be a heavy user of
|
||
Quantum, any entity can make use of any Quantum created network
|
||
so long as it provides an appropriate interfaces for exposing VIFs
|
||
to Quantum itself.
|
||
</para><para>
|
||
Virtual Interfaces(VIF) in the logical model are analogous to
|
||
physical network interface cards (NICs). VIFs are typically
|
||
owned a managed by an external service; for instance when
|
||
Quantum is used for building OpenStack networks,
|
||
VIFs would be created, owned, and managed in Nova.
|
||
VIFs are connected to Quantum networks via ports.
|
||
A port is analogous to a port on a network switch, and it
|
||
has an administrative state. Quantum API
|
||
allows for controlling the administrative state of the port,
|
||
which can be either 'DOWN' or 'ACTIVE'.
|
||
</para><para>
|
||
When a VIF is attached to a port the Quantum API creates
|
||
an attachment object, which specifies the fact that a VIF with a
|
||
given identifier is plugged into the port.
|
||
</para><para>
|
||
The Quantum plugin is responsible for managing virtual and/or
|
||
physical network switches to implement the network forwarding
|
||
connectivity described by the Quantum networks, ports, and
|
||
attachments.
|
||
</para><para>
|
||
VIFs attached to ACTIVE ports are required to have access to the
|
||
L2 broadcast domain defined by the network where they are attached.
|
||
Each VIF shall be capable of exchanging traffic with all other
|
||
entities attached through ACTIVE ports.
|
||
</para>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
</chapter>
|
||
<chapter xml:id="Concepts-d1e369">
|
||
<?dbhtml stop-chunking?>
|
||
<title>Concepts</title>
|
||
<para>
|
||
To use the Quantum API effectively, developers should understand
|
||
the concepts introduced in this chapter.
|
||
</para>
|
||
<section xml:id="Network">
|
||
<title>Network</title>
|
||
<para>
|
||
Each tenant can define one or more networks. A network is a virtual
|
||
isolated layer-2 broadcast domain reserved to the tenant.
|
||
A tenant can create several ports for a network, and plug
|
||
virtual interfaces into these ports.
|
||
</para>
|
||
</section>
|
||
<section xml:id="Port">
|
||
<title>Port</title>
|
||
<para>
|
||
A port represents a virtual switch port on a logical
|
||
network switch where all the interfaces attached to a given
|
||
network are connected.
|
||
</para><para>
|
||
A port has an administrative state which
|
||
is either 'DOWN' or 'ACTIVE'. Ports which are administratively
|
||
down will not be able to receive/send traffic.
|
||
</para>
|
||
</section>
|
||
<section xml:id="Attachment">
|
||
<title>Attachment</title>
|
||
<para>
|
||
An attachment represents an interface plugged into a logical
|
||
port. At any time at most one attachment can be plugged into a
|
||
given port.
|
||
</para><para>
|
||
An attachment typically identified a virtual network interface.
|
||
Network interfaces are typically defined in an external services
|
||
which uses Quantum, for instance the OpenStack Compute service,
|
||
Nova.
|
||
</para>
|
||
</section>
|
||
</chapter>
|
||
<chapter xml:id="General_API_Information-d1e436">
|
||
<title>General API Information</title>
|
||
<para>
|
||
The OpenStack Quantum API is defined as a ReSTful HTTP
|
||
service. The API takes advantage of all aspects of the
|
||
HTTP protocol (methods, URIs, media types, response codes,
|
||
etc.) and providers are free to use existing features of
|
||
the protocol such as caching, persistent connections, and
|
||
content compression among others. For example, providers
|
||
who employ a caching layer may respond with a 203 when a
|
||
request is served from the cache instead of a 200.
|
||
Additionally, providers may offer support for conditional
|
||
&GET; requests using ETags, or they may send a redirect in
|
||
response to a &GET; request. Clients should be written to
|
||
account for these differences.
|
||
</para>
|
||
<section xml:id="Authentication-d1e444">
|
||
<title>Authentication</title>
|
||
<para>
|
||
The current version of the OpenStack Quantum service
|
||
does not require that each request will include the credentials
|
||
of the user submitting the request.
|
||
</para><para>
|
||
However, Quantum deployments can support several
|
||
authentication schemes (OAuth, Basic Auth, Token). The
|
||
authentication scheme used is determined by the
|
||
provider of the Quantum service. Please contact
|
||
your provider to determine the best way to
|
||
authenticate against this API.
|
||
</para><para>
|
||
Ideally, middleware modules for Authentication and/or Authorization
|
||
should be inserted in the first stages of the Quantum pipeline
|
||
(available in <code>etc/quantum.conf</code>).
|
||
</para>
|
||
<note>
|
||
<para>
|
||
Some authentication schemes may require that the
|
||
API operate using SSL over HTTP (HTTPS).
|
||
</para>
|
||
</note>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="URI_structure">
|
||
<title>URI structure</title>
|
||
<para>
|
||
Each request to the OpenStack Quantum API must refer to a
|
||
specific version of the API itself, and it must also
|
||
identify the tenant for which the request is being sent.
|
||
</para>
|
||
<para>
|
||
This information is specified in the URI. The URI
|
||
for each request to the OpenStack Quantum API should be
|
||
prefixed with the API version identifier and the tenant
|
||
identifier, as follows:
|
||
</para>
|
||
<para>
|
||
<code>/{Quantum-version}/tenants/{tenant-id}/{Quantum-API-entity}</code>
|
||
</para>
|
||
<para>
|
||
As an example, the following URI represents a request for
|
||
retrieving all the networks configured for the tenant "ABC"
|
||
using the 1.0 API.
|
||
</para>
|
||
<para>
|
||
<code>/v1.0/ABC/networks</code>
|
||
</para>
|
||
</section>
|
||
<section xml:id="Request_Response_Types">
|
||
<title>Request/Response Types</title>
|
||
<para>
|
||
The OpenStack Quantum API supports both the JSON and XML
|
||
data serialization formats.
|
||
The format for both the request and the response can be
|
||
specified either using the <code>Content-Type</code> header,
|
||
the <code>Accept</code> header or adding an <code>.xml</code>
|
||
or <code>.json</code> extension to the request URI.
|
||
</para><para>
|
||
If conflicting formats are specified in headers and/or format
|
||
extensions, the latter takes precedence. XML is currently
|
||
the default format for both requests and responses.
|
||
</para>
|
||
<table rules="all">
|
||
<caption>JSON and XML Response Formats</caption>
|
||
<thead>
|
||
<tr>
|
||
<td>Format</td>
|
||
<td>Accept Header</td>
|
||
<td>Query Extension</td>
|
||
<td>Default</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>JSON</td>
|
||
<td>application/json</td>
|
||
<td>.json</td>
|
||
<td>No</td>
|
||
</tr>
|
||
<tr>
|
||
<td>XML</td>
|
||
<td>application/xml</td>
|
||
<td>.xml</td>
|
||
<td>Yes</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<example>
|
||
<title>Request/Response with Headers: JSON</title>
|
||
<literallayout class="monospaced">
|
||
POST /v1.0/tenants/tenantX/networks HTTP/1.1
|
||
Host 127.0.0.1:9696
|
||
Accept text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
|
||
Content-Type application/json; charset=UTF-8
|
||
Content-Length 30
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/networks-post-req.json" parse="text"/></programlisting>
|
||
<literallayout class="monospaced">
|
||
HTTP/1.1 200 Accepted
|
||
Content-Type application/json
|
||
Content-Length 59
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/networks-post-res.json" parse="text"/></programlisting>
|
||
</example>
|
||
<para>
|
||
Notice, in the above example, that both the
|
||
<code>Content-Type</code> and the <code>Accept</code>
|
||
headers are specified. The
|
||
<code>Content-Type</code> header always takes precedence
|
||
over the <code>Accept</code> header. The value of the latter
|
||
header is therefore ignored in the example above.
|
||
</para>
|
||
<example>
|
||
<title>Request/Response with Headers: XML</title>
|
||
<literallayout class="monospaced">
|
||
POST /v1.0/tenants/tenantX/networks HTTP/1.1
|
||
Host 127.0.0.1:9696
|
||
Accept text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
|
||
Content-Type application/xml; charset=UTF-8
|
||
Content-Length 22
|
||
</literallayout>
|
||
<programlisting language="xml"><?db-font-size 80%?><xi:include href="samples/networks-post-req.xml" parse="text"/></programlisting>
|
||
<literallayout class="monospaced">
|
||
HTTP/1.1 200 Accepted
|
||
Content-Type application/xml
|
||
Content-Length 52
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/networks-post-res.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Request/Response with Extensions: JSON</title>
|
||
<literallayout class="monospaced">
|
||
POST /v1.0/tenants/tenantX/networks.json HTTP/1.1
|
||
Host 127.0.0.1:9696
|
||
Accept text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
|
||
Content-Type application/json; charset=UTF-8
|
||
Content-Length 30
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/networks-post-req.json" parse="text"/></programlisting>
|
||
<literallayout class="monospaced">
|
||
HTTP/1.1 200 Accepted
|
||
Content-Type application/json
|
||
Content-Length 59
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/networks-post-res.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Async_behaviour">
|
||
<title>Asynchronous Behavior by Quantum Plugins</title>
|
||
<para>
|
||
The Quantum API presents a logical model of network connectivity
|
||
consisting of networks, ports, and attachments. It is up to
|
||
the Quantum plugin to communicate with all managed virtual
|
||
and/or physical switches to ensure that these devices implement
|
||
packet forwarding behavior consistent with the logical model.
|
||
</para><para>
|
||
The plugin's task of mapping from the logical model to the physical
|
||
world might happen asynchronously. This means that when an API
|
||
client modifies the logical model using an HTTP POST, PUT,
|
||
or DELETE, the API call may return prior to the plugin performing
|
||
any modifications to underlying virtual and/or physical switching
|
||
devices. The only guarantee an API client has is that all
|
||
subsequent API calls will properly reflect the changed logical model.
|
||
</para><para>
|
||
As a concrete example, consider the case where a client uses an HTTP
|
||
PUT to set the attachment for a port. There is no guarantee that
|
||
packets sent by the interface named in the attachment will be
|
||
forwarded immediately once the HTTP call returns.
|
||
However, there is a guarantee that a subsequent HTTP GET to view
|
||
the attachment on that port would return the new attachment value.
|
||
</para>
|
||
<note><para>
|
||
Future versions of the API may expose a notion of an "operational status"
|
||
on a logical entity like a network or port.
|
||
</para><para>
|
||
This would indicate whether the Quantum plugin had successfully
|
||
configured virtual and/or physical switches in order to implement
|
||
the network connectivity described by that element of the logical
|
||
model.
|
||
</para><para>
|
||
For example, a port might have an operational status of <code>"DOWN"</code>
|
||
because the VM interface specified as an attachment was not
|
||
currently running on any physical server.
|
||
</para></note>
|
||
</section>
|
||
<section xml:id="Versions">
|
||
<title>Versions</title>
|
||
<para>
|
||
The Quantum API uses a URI based versioning scheme.
|
||
The first element of the URI path contains the target
|
||
version identifier.
|
||
<example>
|
||
<title>Request with URI versioning</title>
|
||
<literallayout class="monospaced">
|
||
GET /v1.0/tenants/tenantX/networks HTTP/1.1
|
||
Host 127.0.0.1:9696
|
||
Accept text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
|
||
Content-Type application/xml; charset=UTF-8
|
||
Content-Length 22
|
||
</literallayout>
|
||
</example>
|
||
</para>
|
||
<para>
|
||
Available API versions can be retrieved
|
||
by performing a &GET; on the root URL
|
||
(i.e. with the version and everything to the
|
||
right of it truncated) of the Quantum Service.
|
||
</para>
|
||
<example>
|
||
<title>Versions List Request/Response (XML)</title>
|
||
<literallayout class="monospaced">
|
||
GET / HTTP/1.1
|
||
Host 127.0.0.1:9696
|
||
Content-Type application/xml
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/versions.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
|
||
|
||
<example>
|
||
<title>Version List Request/Response: JSON</title>
|
||
<literallayout class="monospaced">
|
||
GET / HTTP/1.1
|
||
Host 127.0.0.1:9696
|
||
Content-Type application/json
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include
|
||
href="samples/versions.json" parse="text"/></programlisting>
|
||
</example>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Extensions">
|
||
<title>Extensions</title>
|
||
<para>
|
||
The Quantum API is extensible. Extensions
|
||
serve several purposes:
|
||
</para>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
They allow the introduction of new
|
||
features in the API without requiring a
|
||
version change;
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
They allow the introduction of vendor specific
|
||
niche functionality
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
They act as a proving ground for experimental
|
||
functionalities which might be included in a future
|
||
version of the API.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
Applications can programmatically
|
||
determine what extensions are available by performing
|
||
a &GET; on the <code>/v1.0/extensions</code> URI.
|
||
Note that this is a versioned request — that is,
|
||
an extension available in one API version may not be
|
||
available in another.
|
||
</para>
|
||
<example>
|
||
<title>Extensions Response: XML</title>
|
||
<programlisting language="xml"><?db-font-size 90%?>
|
||
<xi:include href="samples/extensions.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Extensions Response: JSON</title>
|
||
<programlisting language="javascript"><?db-font-size 90%?><xi:include
|
||
href="samples/extensions.json" parse="text"/></programlisting>
|
||
</example>
|
||
<para>
|
||
Extensions may also be queried individually by their unique alias by performing
|
||
a &GET; on the <code>/v1.0/extensions/alias_name</code>. This provides the simplest
|
||
method of checking if an extension is available as an unavailable extension will issue an
|
||
itemNotFound (404) response.
|
||
</para>
|
||
<para>
|
||
<note>
|
||
Existing core API resources can be extended with new actions or extra data in request/response of existing actions.
|
||
Further new resources can also be added as extensions.
|
||
Extensions usually have vendor specific tags that prevent clash with other extensions.
|
||
Availability of an extension will vary with deployments and the specific plugin in use.
|
||
</note>
|
||
</para>
|
||
<important>
|
||
<para>
|
||
Applications should be prepared to ignore response
|
||
data that contains extension elements.
|
||
Applications should also verify that an extension
|
||
is available before submitting an extended request.
|
||
</para>
|
||
</important>
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<section xml:id="Faults">
|
||
<title>Faults</title>
|
||
<para>
|
||
When an error occurs at request time, the system
|
||
will return an HTTP error response code denoting
|
||
the type of error. The system will also return
|
||
additional information about the fault in the body
|
||
of the response.
|
||
</para>
|
||
<example>
|
||
<title>"Network not found" fault Response (XML)</title>
|
||
<programlisting language="xml"><xi:include href="samples/fault.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>"Network not found" fault Response (JSON)</title>
|
||
<programlisting language="javascript"><xi:include href="samples/fault.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<para> The error code is returned in the body of the response for convenience. The
|
||
message section returns a human-readable message that is appropriate for display to
|
||
the end user. The detail section is optional and may contain information—for example, a stack trace—to
|
||
assist in tracking down an error.
|
||
</para>
|
||
<para>
|
||
The root element of the fault (e.g. networkNotFound)
|
||
may change depending on the type of error. The
|
||
following is a list of possible elements along with
|
||
their associated error codes.
|
||
</para>
|
||
<?hard-pagebreak?>
|
||
<table rules="all">
|
||
<caption>Fault Elements and Error Codes</caption>
|
||
<thead>
|
||
<tr>
|
||
<td>Fault Element</td>
|
||
<td>Error Code</td>
|
||
<td colspan="2">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td bgcolor="#4F91BD">BadRequest</td>
|
||
<td bgcolor="#4F91BD">400</td>
|
||
<td bgcolor="#4F91BD" colspan="2">
|
||
Malformed request body.
|
||
The Quantum service is unable to parse the contents of the
|
||
request body.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>Unauthorized</td>
|
||
<td>401</td>
|
||
<td colspan="2">
|
||
User has not provided authentication credentials.
|
||
If authentication is provided by the Keystone identity
|
||
service, this might mean that either no authentication
|
||
token has been supplied in the request, or that the
|
||
token itself is either invalid or expired.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td bgcolor="#4F91BD">Forbidden</td>
|
||
<td bgcolor="#4F91BD">403</td>
|
||
<td bgcolor="#4F91BD" colspan="2">
|
||
The user does not have the necessary rights
|
||
to execute the requested operation
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>ItemNotFound</td>
|
||
<td>404</td>
|
||
<td colspan="2">
|
||
The requested resource does not exist on the Quantum API server
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td bgcolor="#4F91BD">NetworkNotFound</td>
|
||
<td bgcolor="#4F91BD">420</td>
|
||
<td bgcolor="#4F91BD" colspan="2">
|
||
The specified network has not been created or has been removed.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>NetworkInUse</td>
|
||
<td>421</td>
|
||
<td colspan="2">
|
||
The specified network has attachments plugged into one or more of its ports.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td bgcolor="#4F91BD">PortNotFound</td>
|
||
<td bgcolor="#4F91BD">430</td>
|
||
<td bgcolor="#4F91BD" colspan="2">
|
||
The specified port has not been created or has been removed.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>RequestedStateInvalid</td>
|
||
<td>431</td>
|
||
<td colspan="2">
|
||
Indicates a request to change port to an administrative
|
||
state not currently supported.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td bgcolor="#4F91BD">PortInUse</td>
|
||
<td bgcolor="#4F91BD">432</td>
|
||
<td bgcolor="#4F91BD" colspan="2">
|
||
The specified port cannot be removed as there is an attachment plugged in it.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>AlreadyAttached</td>
|
||
<td>440</td>
|
||
<td colspan="2">
|
||
Attachment is already plugged into another port.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<note>
|
||
<para>
|
||
The error codes 401 and 403 will be returned only if some
|
||
Authentication/Authorization system has been enabled in the
|
||
Quantum pipeline
|
||
</para>
|
||
</note>
|
||
</section>
|
||
</chapter>
|
||
<chapter xml:id="API_Operations">
|
||
<title>API Operations</title>
|
||
<section xml:id="Networks">
|
||
<title>Networks</title>
|
||
<para>
|
||
This section describes the operations exposed by Quantum API for
|
||
manipulating network resources.
|
||
</para>
|
||
<section xml:id="List_Networks">
|
||
<title>List Networks</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks</td>
|
||
<td colspan="3">
|
||
List summary of networks configured in Quantum for
|
||
a given tenant, identified by tenant-id
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation returns the list of all networks
|
||
currently defined in Quantum for the tenant
|
||
specified in the request URI.
|
||
The returned list will provide the unique identifier
|
||
of each network configured for the tenant specified
|
||
in the resource URI.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
<property>TenantId</property> is a unique tenant
|
||
identifier. The Quantum service does not directly
|
||
manages tenants. Tenant management should be
|
||
performed by the identity service
|
||
</para>
|
||
</note>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Networks List Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/networks-get-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Networks List Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/networks-get-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="List_Networks_Detail">
|
||
<title>List Networks Details</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/detail</td>
|
||
<td colspan="3">
|
||
List more detailed information about networks
|
||
configured in Quantum for a given tenant,
|
||
identified by tenant-id
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation returns the list of all networks currently
|
||
defined in Quantum; for each network, its identifier
|
||
and name are returned.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Networks List Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/detail.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/networks-get-detail-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pageb reak?>
|
||
<example>
|
||
<title>Networks List Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/detail.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/networks-get-detail-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Show_Network">
|
||
<title>Show Network</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis></td>
|
||
<td colspan="3">
|
||
List information for a specific network,
|
||
identified by <emphasis>network-id</emphasis>,
|
||
for a given tenant, identified by <emphasis>tenant-id</emphasis>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
</simpara>
|
||
<para>
|
||
This operation returns the identifier and the name for a
|
||
specific network configured in Quantum.
|
||
</para><para>
|
||
This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Show Network Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/network-get-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Show Network Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/network-get-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Show_Network_Detail">
|
||
<title>Show Network Details</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis>/detail</td>
|
||
<td colspan="3">
|
||
List detailed information for a specific network,
|
||
identified by <emphasis>network-id</emphasis>,
|
||
for a given tenant, identified by <emphasis>tenant-id</emphasis>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
</simpara>
|
||
<para>
|
||
This operation returns detailed information concerning the
|
||
network specified in the request URI. Returned data include
|
||
the full list of ports configured for the network
|
||
and attachments plugged into such ports.
|
||
</para><para>
|
||
If no attachment is plugged into a port, the response will
|
||
not include an <code>attachment</code> child element for that
|
||
port.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Show Network Detail Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3/detail.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/network-get-detail-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Show Network Detail Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3/detail.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/network-get-detail-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Create_Network">
|
||
<title>Create Network</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks</td>
|
||
<td colspan="3">
|
||
Creates a new logical layer-2 network for the
|
||
tenant identified by <emphasis>tenant-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
BadRequest (<errorcode>400</errorcode>)
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
</simpara>
|
||
<para>
|
||
This operation creates a Layer-2 network in
|
||
Quantum based on the information provided in the request body.
|
||
</para><para>
|
||
Quantum validates the request, and dispatches it to the plugin,
|
||
and then returns the unique identifier of the network to the
|
||
caller. Although the network API entity can be immediately used
|
||
for other operations, this does not guarantee that the network
|
||
will be available when the API call returns, as this depends
|
||
on the particular plugin implementation.
|
||
</para><para>
|
||
If the validation phase fails, the network object is not
|
||
created at all, and a 400 error is returned to the caller.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
The Quantum API v1.0 does not provide an interface
|
||
for checking the progress of asynchronous operations
|
||
performed by plugins.
|
||
</para>
|
||
<para>
|
||
This will be addressed in future releases of the
|
||
Quantum API.
|
||
</para>
|
||
</note>
|
||
<para>
|
||
The body for this request must contain a Network object
|
||
specifying a symbolic name for the network.
|
||
</para>
|
||
<example>
|
||
<title>Create Network Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
POST /tenants/XYZ/networks.xml
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/network-post-req.xml" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/network-post-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Create Network Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
POST /tenants/XYZ/networks.json
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/network-post-req.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/network-post-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Update_Network">
|
||
<title>Update Network</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis></td>
|
||
<td colspan="3">
|
||
Renames the network identified by
|
||
<emphasis>network-id</emphasis> for the
|
||
tenant identified by <emphasis>tenant-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
BadRequest (<errorcode>400</errorcode>)
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation renames a Quantum network using the data
|
||
provided in the request body.
|
||
</para>
|
||
<para>
|
||
The body for this request must contain a Network object
|
||
specifying a symbolic name for the network. The network
|
||
entity specified in the request body can contain the
|
||
network's identifier as well, even if it is not required,
|
||
as the identifier must be expressed on the URI; in this
|
||
case the identifier in the request body will be ignored.
|
||
</para>
|
||
<example>
|
||
<title>Update Network Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/network-post-req.xml" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Update Network Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json
|
||
</literallayout>
|
||
<programlisting language="javascript"><xi:include href="samples/network-post-req.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body</emphasis></para>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Delete_Network">
|
||
<title>Delete Network</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis></td>
|
||
<td colspan="3">
|
||
Destroys the network identified by
|
||
<emphasis>network-id</emphasis> for the
|
||
tenant identified by <emphasis>tenant-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
BadRequest (<errorcode>400</errorcode>)
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
NetworkInUse (<errorcode>421</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation removes the network specified in the URI.
|
||
This request will fail as long as there is at least one
|
||
port on the network with attachments plugged in it.
|
||
If all ports on the networks are unattached, they will
|
||
be destroyed together with the network itself.
|
||
</para>
|
||
<para>
|
||
As for the create operation there is no guarantee that the
|
||
plugin will have completely removed the network when the
|
||
call returns. Quantum forwards the request to the plugin,
|
||
which will then destroy the network.
|
||
</para><para>
|
||
Please note that this operation cannot be undone.
|
||
</para>
|
||
<para>
|
||
This operation does not require a request body.
|
||
</para>
|
||
<example>
|
||
<title>Delete Network Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Update Network Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body</emphasis></para>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
<section xml:id="Ports">
|
||
<title>Ports</title>
|
||
<para>
|
||
This section describes the operations exposed by Quantum API for
|
||
manipulating port resources.
|
||
</para>
|
||
<section xml:id="List_Ports">
|
||
<title>List Ports</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}/ports</emphasis></td>
|
||
<td colspan="3">
|
||
Lists all the ports currently defined for a Quantum network,
|
||
identified by <emphasis>network-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation lists all the ports currently configured
|
||
for a network. For each port the response reports its
|
||
unique identifier. If no ports have been
|
||
created on the network an empty list will be returned.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Port List Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/ports-get-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Port List Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/ports-get-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="List_Ports_Details">
|
||
<title>List Ports Details</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/detail</td>
|
||
<td colspan="3">
|
||
Lists detailed information for all the ports currently defined
|
||
for the network identified by <emphasis>network-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation lists detailed information for all the ports
|
||
currently configured for a network. Response for each port
|
||
includes its identifier and the current administrative state.
|
||
If no ports have been created on the network an
|
||
empty list will be returned.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Port List Details Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/detail.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/ports-get-detail-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Port List Details Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/detail.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/ports-get-detail-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Show_port">
|
||
<title>Show Port</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/
|
||
<emphasis>{port-id}</emphasis></td>
|
||
<td colspan="3">
|
||
Retrieves the port
|
||
<emphasis>port-id</emphasis> configured for the
|
||
network <emphasis>network-id</emphasis> belonging
|
||
to the tenant <emphasis>tenant-id</emphasis>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
PortNotFound (<errorcode>430</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation returns the unique identifier and the
|
||
current administrative state for a specific port configured
|
||
for the network specified in the request URI.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Show Port Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/port-get-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Show Port Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/port-get-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Show_port_Details">
|
||
<title>Show Port Details</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/
|
||
<emphasis>{port-id}</emphasis>/detail</td>
|
||
<td colspan="3">
|
||
Retrieves detailed information for the port
|
||
<emphasis>port-id</emphasis> configured for the
|
||
network <emphasis>network-id</emphasis> belonging
|
||
to the tenant <emphasis>tenant-id</emphasis>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
PortNotFound (<errorcode>430</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation provides at least the identifier and the
|
||
current administrative state for specific port configured
|
||
for a given network.
|
||
</para><para>
|
||
If an attachment is plugged into the port, this operation
|
||
will return the identifier of the attachment as well.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Show Port Detail Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855/detail.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/port-get-detail-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Show Port Detail Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855/detail.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/port-get-detail-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Create_Port">
|
||
<title>Create Port</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&POST;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports</td>
|
||
<td colspan="3">
|
||
Creates a port on the network specified
|
||
in the request URI, identified by
|
||
<emphasis>network-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
BadRequest (<errorcode>400</errorcode>),
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
RequestedStateInvalid (<errorcode>431</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation creates a port on a Quantum network based on
|
||
the information provided in the request body.
|
||
Quantum validates the request, and dispatches the request
|
||
to the plugin, which creates the port and attaches
|
||
it to the appropriate network.
|
||
</para><para>
|
||
This operation could not be implemented for some
|
||
plugins as the number of ports available might be fixed
|
||
when the network is created.
|
||
</para><para>
|
||
If the validation phase fails, the port object is not
|
||
created at all, and a <code>BadRequest</code> error is returned
|
||
to the caller.
|
||
</para><para>
|
||
The operation returns a port with an identifier, and set its
|
||
administrative state set to <code>DOWN</code>, unless a state
|
||
has been explicitly specified in the request body.
|
||
</para><para>
|
||
Please note that this operation does not guarantee that the
|
||
port has been actually created when the calls returns,
|
||
as the plugin might still be performing the necessary
|
||
operations on the network infrastructure. However, the port
|
||
entity can be immediately used for API operations.
|
||
</para><para>
|
||
The request body is not mandatory for this operation,
|
||
but it can optionally contain the administrative state
|
||
for the port being created, which can be either
|
||
<code>DOWN</code> or <code>ACTIVE</code>.
|
||
The administrative state should be encapsulated into a Port
|
||
object within the request body, as shown in the example below.
|
||
</para>
|
||
<example>
|
||
<title>Create Port Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
POST /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.xml
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/port-post-req.xml" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<programlisting language="xml"><xi:include href="samples/port-post-res.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Create Port Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
POST /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.json
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/port-post-req.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<programlisting language="javascript"><xi:include href="samples/port-post-res.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Update_Port">
|
||
<title>Update Port</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/
|
||
<emphasis>{port-id}</emphasis></td>
|
||
<td colspan="3">
|
||
Sets the administrative state for the port
|
||
identified by <emphasis>port-id</emphasis>
|
||
on the network identified by
|
||
<emphasis>network-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
BadRequest (<errorcode>400</errorcode>),
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
PortNotFound (<errorcode>430</errorcode>),
|
||
RequestedStateInvalid (<errorcode>431</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation sets the administrative state for a port.
|
||
Currently Quantum recognizes two port states:
|
||
<code>DOWN</code> and <code>ACTIVE</code>. In the
|
||
<code>DOWN</code> state a port will not provide
|
||
connectivity to the network.
|
||
</para><para>
|
||
This feature allows the tenant the ability to take entities
|
||
offline without affecting the logical topology.
|
||
</para><para>
|
||
The operation will return the <code>RequestedStateInvalid</code>
|
||
error code if the specified administrative state is not either
|
||
<code>DOWN</code> or <code>ACTIVE</code>.
|
||
</para><para>
|
||
The operation's request body must contain a Port object with
|
||
the new administrative state for the port.
|
||
</para>
|
||
<example>
|
||
<title>Set Port State Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/port-post-req.xml" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body.</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Create Port Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/port-post-req.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body.</emphasis></para>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Delete_Port">
|
||
<title>Delete Port</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&DELETE;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/
|
||
<emphasis>{port-id}</emphasis></td>
|
||
<td colspan="3">
|
||
Destroys the port
|
||
identified by <emphasis>port-id</emphasis>
|
||
on the network identified by
|
||
<emphasis>network-id</emphasis>
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
BadRequest (<errorcode>400</errorcode>),
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
PortNotFound (<errorcode>430</errorcode>),
|
||
PortInUse (<errorcode>432</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation removes a port from a Quantum network.
|
||
This operation might not be available for plugins in
|
||
which the number of ports is fixed at network creation;
|
||
in this case ports should not be deleted, just as they
|
||
cannot be created.
|
||
</para><para>
|
||
The operation is not recoverable and will fail if an
|
||
attachment is plugged into the port. #
|
||
</para><para>
|
||
This operation does not require a request body.
|
||
</para>
|
||
<example>
|
||
<title>Delete Port State Request/Response (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body.</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Create Port Request/Response (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data returned in response body.</emphasis></para>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
<section xml:id="Attachments">
|
||
<title>Attachments</title>
|
||
<para>
|
||
This section describes the operations exposed by Quantum API for
|
||
manipulating port attachments.
|
||
</para><para>
|
||
An attachment is typically a virtual network interface
|
||
belonging to a VM instance. Different kinds of resources
|
||
can be defined in the future.
|
||
</para>
|
||
<section xml:id="Show_Attachment">
|
||
<title>Show Attachment for Port</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&GET;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/
|
||
<emphasis>{port-id}</emphasis>/attachment</td>
|
||
<td colspan="3">
|
||
Returns the identifier of the attachment plugged
|
||
into the specified port, identified by
|
||
<emphasis>port-id</emphasis>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>200</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
PortNotFound (<errorcode>430</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation returns configuration details for the
|
||
attachment plugged into the port specified in the request URI.
|
||
This information is a reference to a virtual interface
|
||
identifier.
|
||
</para><para>
|
||
If no attachment is currently plugged into the port,
|
||
the operation does not return any attachment
|
||
identifier in the response.
|
||
The response will contain an empty <code>attachment</code> element
|
||
with no <code>id</code> attribute set.
|
||
</para>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Show Attachment (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml
|
||
</literallayout>
|
||
<para>Response (attachment set):</para>
|
||
<programlisting language="xml"><xi:include href="samples/att-get-res.xml" parse="text"/>
|
||
</programlisting>
|
||
<para>Response (attachment not set):</para>
|
||
<programlisting language="xml"><xi:include href="samples/att-get-res-none.xml" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
<example>
|
||
<title>Show Attachment (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json
|
||
</literallayout>
|
||
<para>Response (attachment set):</para>
|
||
<programlisting language="javascript"><xi:include href="samples/att-get-res.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response (attachment not set):</para>
|
||
<programlisting language="javascript"><xi:include href="samples/att-get-res-none.json" parse="text"/>
|
||
</programlisting>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Put_Attachment">
|
||
<title>Plug Attachment into Port</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&PUT;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/
|
||
<emphasis>{port-id}</emphasis>/attachment</td>
|
||
<td colspan="3">
|
||
Plugs a resource, i.e. a virtual network interface
|
||
into the port identified by
|
||
<emphasis>port-id</emphasis>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
PortNotFound (<errorcode>430</errorcode>),
|
||
PortInUse (<errorcode>432</errorcode>),
|
||
AlreadyAttached (<errorcode>440</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation plugs an attachment into the port
|
||
specified in the request URL.
|
||
</para><para>
|
||
The request will be first validated by Quantum and then
|
||
dispatched to the plugin. It is not guaranteed that the
|
||
attached resource will be available as soon as the
|
||
operation returns.
|
||
</para><para>
|
||
The validation can fail if:
|
||
</para>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>
|
||
An attachment with the same identifier
|
||
is already plugged somewhere else;
|
||
</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
There is already another attachment plugged
|
||
into the specified port.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>
|
||
If the validation phase fails, the attachment is not
|
||
created at all, and the appropriate error code is
|
||
returned to the caller.
|
||
</para>
|
||
<para>
|
||
If no attachment is currently plugged into the port,
|
||
the operation does not return any attachment
|
||
identifier in the response.
|
||
The response will contain an empty <code>attachment</code> element.
|
||
</para>
|
||
<para>
|
||
The request body for this network should contain a reference
|
||
to the attachment to plug into the port.
|
||
</para>
|
||
<example>
|
||
<title>Plug Attachment (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/att-put-req.xml" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<para>No data returned in response body</para>
|
||
</example>
|
||
<example>
|
||
<title>Plug Attachment (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/att-put-req.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<para>No data returned in response body</para>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Delete_Attachment">
|
||
<title>Unplug Attachment from Port</title>
|
||
<informaltable rules="all">
|
||
<thead>
|
||
<tr>
|
||
<td colspan="1">Verb</td>
|
||
<td colspan="2">URI</td>
|
||
<td colspan="3">Description</td>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td colspan="1">&DELETE;</td>
|
||
<td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
|
||
<emphasis>{network-id}</emphasis>/ports/
|
||
<emphasis>{port-id}</emphasis>/attachment</td>
|
||
<td colspan="3">
|
||
Removes the attachment currently plugged
|
||
into the port identified by
|
||
<emphasis>port-id</emphasis>.
|
||
</td>
|
||
</tr>
|
||
</tbody>
|
||
</informaltable>
|
||
<simpara>
|
||
Normal Response Code(s):
|
||
<returnvalue>204</returnvalue>
|
||
</simpara>
|
||
<simpara>
|
||
Error Response Code(s):
|
||
Unauthorized (<errorcode>401</errorcode>),
|
||
Forbidden (<errorcode>403</errorcode>),
|
||
NetworkNotFound (<errorcode>420</errorcode>),
|
||
PortNotFound (<errorcode>430</errorcode>)
|
||
</simpara>
|
||
<para>
|
||
This operation removes the attachment from the port
|
||
specified in the request URI.
|
||
</para><para>
|
||
If no attachment is currently plugged into the port,
|
||
this operation has no effect.
|
||
</para>
|
||
<para>
|
||
This operation does not require a request body
|
||
</para>
|
||
<example>
|
||
<title>Remove Attachment (XML)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<para>No data returned in response body</para>
|
||
</example>
|
||
<example>
|
||
<title>Remove Attachment (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">
|
||
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json
|
||
</literallayout>
|
||
<para>Response:</para>
|
||
<para>No data returned in response body</para>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
</chapter>
|
||
</book>
|