b51a471b55
Remove extra whitespace like whitespace at end of line or before a closing </para>. Also, change tabs to spaces. Change-Id: I43d5418cc6c21736a29921e88774cdfdadc09b28
1859 lines
100 KiB
XML
1859 lines
100 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>
|
||
<imagedata fileref="figures/Check_mark_23x20_02.svg"
|
||
format="SVG" scale="60"/>
|
||
</imageobject>
|
||
</inlinemediaobject>'>
|
||
|
||
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
|
||
<imageobject>
|
||
<imagedata fileref="figures/Arrow_east.svg"
|
||
format="SVG" scale="60"/>
|
||
</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>
|
||
<?rax pdf.url="../quantum-api-guide-1.0.pdf"?>
|
||
<titleabbrev>Quantum API 1.0</titleabbrev>
|
||
<info>
|
||
<author>
|
||
<personname>
|
||
<firstname/>
|
||
<surname/>
|
||
</personname>
|
||
</author>
|
||
<copyright>
|
||
<year>2011</year><year>2012</year>
|
||
<holder>OpenStack</holder>
|
||
</copyright>
|
||
<releaseinfo>Quantum API v1.0</releaseinfo>
|
||
<productname>OpenStack Quantum (virtual network service)</productname>
|
||
<pubdate>2012-04-18</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>
|
||
<revhistory>
|
||
<revision>
|
||
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
|
||
<date>2012-08-08</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Corrected the titles of some
|
||
examples.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision><!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
|
||
<date>2012-04-18</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Fixed incorrect mention of &PUT;
|
||
verb in <xref linkend="Delete_Network"
|
||
/>. Verb changed to &DELETE;.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Fixed formatting issues in request
|
||
and response examples.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision><revision><!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
|
||
<date>2011-09-22</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Initial release.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>First edition of this document.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
</revhistory>
|
||
</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>This version of the document replaces and obsoletes all
|
||
previous versions. The following table describes the most
|
||
recent changes:</para>
|
||
<?rax revhistory?><!-- Table generated in output from revision element in the book element -->
|
||
</section>
|
||
<?hard-pagebreak?>
|
||
<!-- <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">April 18, 2012</td>
|
||
<td colspan="4">
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Corrected verb in
|
||
delete networks API operation to
|
||
DELETE from PUT.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>
|
||
Cleaned up miscellaneous code formatting issues.
|
||
</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td colspan="1">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">Any piece of hardware or
|
||
software that wants to connect to the
|
||
network services provided by Quantum. An
|
||
entity can use Quantum network services by
|
||
implementing a VIF.</td>
|
||
</tr>
|
||
<tr>
|
||
<!-- <td colspan="1" align="center" bgcolor="#4F91BD"> --> <td colspan="1" align="center">Layer-2 network
|
||
</td>
|
||
<!-- <td colspan="4" bgcolor="#4F91BD"> --><td colspan="4">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
|
||
such as, a 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"> --> <td align="center">
|
||
Plugin
|
||
</td>
|
||
<!-- <td colspan="4" bgcolor="#4F91BD"> -->
|
||
<td colspan="4">Software component that
|
||
provides 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"> -->
|
||
<td align="center">
|
||
VIF
|
||
</td>
|
||
<!-- <td colspan="4" bgcolor="#4F91BD"> --> <td colspan="4">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">The association of an
|
||
interface identifier to a logical port,
|
||
which represents '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>
|
||
<para>Request:</para> <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="json"><xi:include href="samples/networks-post-req.json" parse="text"/></programlisting>
|
||
<para>Response:</para> <literallayout class="monospaced">
|
||
HTTP/1.1 200 Accepted
|
||
Content-Type application/json
|
||
Content-Length 59
|
||
</literallayout>
|
||
<programlisting language="json"><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>
|
||
<para>Request:</para> <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>
|
||
<para>Response:</para> <literallayout class="monospaced">
|
||
HTTP/1.1 200 Accepted
|
||
Content-Type application/xml
|
||
Content-Length 52
|
||
</literallayout>
|
||
<programlisting language="xml"><xi:include href="samples/networks-post-res.xml" parse="text"/></programlisting>
|
||
</example>
|
||
<?hard-pagebreak?>
|
||
<example>
|
||
<title>Request/Response with Extensions: JSON</title>
|
||
<para>Request:</para> <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="json"><xi:include href="samples/networks-post-req.json" parse="text"/></programlisting>
|
||
<para>Response:</para> <literallayout class="monospaced">
|
||
HTTP/1.1 200 Accepted
|
||
Content-Type application/json
|
||
Content-Length 59
|
||
</literallayout>
|
||
<programlisting language="json"><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="json"><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="json"><?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>
|
||
|
||
<note><para>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.
|
||
</para></note>
|
||
|
||
<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 (XML)</title>
|
||
<programlisting language="json"><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"> --><td>BadRequest</td>
|
||
<!-- <td bgcolor="#4F91BD"> --><td>400</td>
|
||
<!-- <td bgcolor="#4F91BD" colspan="2"> --><td 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"> --><td>Forbidden</td>
|
||
<!-- <td bgcolor="#4F91BD"> --> <td>403</td>
|
||
<!-- <td bgcolor="#4F91BD" colspan="2"> --> <td 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"> --><td>NetworkNotFound</td>
|
||
<!-- <td bgcolor="#4F91BD"> --><td>420</td>
|
||
<!-- <td bgcolor="#4F91BD" colspan="2"> --> <td 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"> --><td>PortNotFound</td>
|
||
<!-- <td bgcolor="#4F91BD"> --><td>430</td>
|
||
<!-- <td bgcolor="#4F91BD" colspan="2"> --><td 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"> --> <td>PortInUse</td>
|
||
<!--> <td bgcolor="#4F91BD"> --> <td>432</td>
|
||
<!-- <td bgcolor="#4F91BD" colspan="2"> --><td 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/<parameter>tenant-id</parameter>/networks</td>
|
||
<td colspan="3">Lists summary of networks
|
||
configured in Quantum for a given
|
||
tenant, identified by
|
||
<parameter>tenant-id</parameter>.</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 list provides
|
||
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="json"><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/<parameter>tenant-id</parameter>/networks/detail</td>
|
||
<td colspan="3">Lists more detailed
|
||
information about networks configured
|
||
in Quantum for a given tenant,
|
||
identified by <parameter>tenant-id</parameter>.</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 Details 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 Details Request/Response
|
||
(JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">GET /tenants/XYZ/networks/detail.json</literallayout>
|
||
<para>Response:</para>
|
||
<programlisting language="json"><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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter></td>
|
||
<td colspan="3">Lists information for a
|
||
specific network, identified by
|
||
<parameter>network-id</parameter>,
|
||
for a given tenant, identified by
|
||
<parameter>tenant-id</parameter>.</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="json"><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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter>/detail</td>
|
||
<td colspan="3">Lists detailed information
|
||
for a specific network, identified by
|
||
<parameter>network-id</parameter>,
|
||
for a given tenant, identified by
|
||
<parameter>tenant-id</parameter>.</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 Details 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 Details 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="json"><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/<parameter>tenant-id</parameter>/networks</td>
|
||
<td colspan="3">Creates a new logical
|
||
layer-2 network for the tenant
|
||
identified by
|
||
<parameter>tenant-id</parameter>.</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="json"><xi:include href="samples/network-post-req.json" parse="text"/> </programlisting>
|
||
<para>Response:</para>
|
||
<programlisting language="json"><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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter></td>
|
||
<td colspan="3">Renames the network
|
||
identified by
|
||
<parameter>network-id</parameter> for
|
||
the tenant identified by
|
||
<parameter>tenant-id</parameter>.</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 (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 is returned in the
|
||
response body.</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Update Network Request (JSON)</title>
|
||
<para>Request:</para>
|
||
<literallayout class="monospaced">PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json </literallayout>
|
||
<programlisting language="json"><xi:include href="samples/network-post-req.json" parse="text"/> </programlisting>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data is returned in the
|
||
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">&DELETE;</td>
|
||
<td colspan="2">/tenants/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter></td>
|
||
<td colspan="3">Destroys the network
|
||
identified by
|
||
<parameter>network-id</parameter> for
|
||
the tenant identified by
|
||
<parameter>tenant-id</parameter>.</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>
|
||
<note><para>This operation cannot be undone.</para></note>
|
||
<para>This operation does not require a request body.</para>
|
||
<example>
|
||
<title>Delete Network Request (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 is returned in the
|
||
response body.</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Delete Network Request (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 is returned in the
|
||
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/<parameter>tenant-id</parameter>/networks/
|
||
<parameter>network-id/ports</parameter></td>
|
||
<td colspan="3">
|
||
Lists all the ports currently defined for a Quantum network,
|
||
identified by <parameter>network-id</parameter>
|
||
</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="json"><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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter>/ports/detail</td>
|
||
<td colspan="3">Lists detailed information
|
||
for all the ports currently defined
|
||
for the network identified by
|
||
<parameter>network-id</parameter>.
|
||
</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="json"><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/<parameter>tenant-id</parameter>/networks/
|
||
<parameter>network-id</parameter>/ports/
|
||
<parameter>port-id</parameter></td>
|
||
<td colspan="3">Retrieves the port
|
||
<parameter>port-id</parameter>
|
||
configured for the network
|
||
<parameter>network-id</parameter>
|
||
belonging to the tenant
|
||
<parameter>tenant-id</parameter>.</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="json"><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/<parameter>tenant-id</parameter>/networks/
|
||
<parameter>network-id</parameter>/ports/
|
||
<parameter>port-id</parameter>/detail</td>
|
||
<td colspan="3">Retrieves detailed
|
||
information for the port
|
||
<parameter>port-id</parameter>
|
||
configured for the network
|
||
<parameter>network-id</parameter>
|
||
belonging to the tenant
|
||
<parameter>tenant-id</parameter>.</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 Details 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 Details 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="json"><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/<parameter>tenant-id</parameter>/networks/
|
||
<parameter>network-id</parameter>/ports</td>
|
||
<td colspan="3">Creates a port on the
|
||
network specified in the request URI,
|
||
identified by
|
||
<parameter>network-id</parameter>.</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>
|
||
<note><para>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></note>
|
||
<para>The request body is not required 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="json"><xi:include href="samples/port-post-req.json" parse="text"/> </programlisting>
|
||
<para>Response:</para>
|
||
<programlisting language="json"><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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter>/ports/<parameter>port-id</parameter></td>
|
||
<td colspan="3">Sets the administrative
|
||
state for the port identified by
|
||
<parameter>port-id</parameter> on
|
||
the network identified by
|
||
<parameter>network-id</parameter>.</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>Update Port Request (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 is returned in the response
|
||
body.</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Update Port Request (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="json"><xi:include href="samples/port-post-req.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response:</para>
|
||
<para><emphasis>No data is returned in the
|
||
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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter>/ports/<parameter>port-id</parameter></td>
|
||
<td colspan="3">Destroys the port
|
||
identified by
|
||
<parameter>port-id</parameter> on
|
||
the network identified by
|
||
<parameter>network-id</parameter>.</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 Request (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 is returned in the response
|
||
body..</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Delete Port Request (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 is returned in the
|
||
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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter>/ports/<parameter>port-id</parameter>/attachment</td>
|
||
<td colspan="3">Returns the identifier of
|
||
the attachment plugged into the
|
||
specified port, identified by
|
||
<parameter>port-id</parameter>.</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 Request/Response
|
||
(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 Request/Response
|
||
(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="json"><xi:include href="samples/att-get-res.json" parse="text"/>
|
||
</programlisting>
|
||
<para>Response (attachment not set):</para>
|
||
<programlisting language="json"><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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter>/ports/<parameter>port-id</parameter>/attachment</td>
|
||
<td colspan="3">Plugs a resource, such as
|
||
a virtual network interface, into the
|
||
port identified by
|
||
<parameter>port-id</parameter>.</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>Quantum validates the request and dispatches the request 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 in somewhere else.</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>Another attachment is already plugged into
|
||
the specified port.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
<para>If validation 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 Request (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><emphasis role="italic">No data is returned
|
||
in the response body.</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Plug Attachment Request (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><emphasis role="italic">No data is returned in the response
|
||
body.</emphasis></para>
|
||
</example>
|
||
</section>
|
||
<section xml:id="Delete_Attachment">
|
||
<title>Delete 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/<parameter>tenant-id</parameter>/networks/<parameter>network-id</parameter>/ports/<parameter>port-id</parameter>/attachment</td>
|
||
<td colspan="3">Removes the attachment
|
||
currently plugged into the port
|
||
identified by
|
||
<parameter>port-id</parameter>.</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 specified 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>Delete Attachment Request (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><emphasis role="italic">No data is returned
|
||
in the response body.</emphasis></para>
|
||
</example>
|
||
<example>
|
||
<title>Delete Attachment Request (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><emphasis role="italic">No data is returned
|
||
in the response body.</emphasis></para>
|
||
</example>
|
||
</section>
|
||
</section>
|
||
</chapter>
|
||
</book>
|