1850 lines
96 KiB
XML
1850 lines
96 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>
|
||
<year>2013</year>
|
||
<year>2014</year>
|
||
<holder>OpenStack</holder>
|
||
</copyright>
|
||
<releaseinfo>Quantum API v1.0</releaseinfo>
|
||
<productname>OpenStack Quantum (virtual network
|
||
service)</productname>
|
||
<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>
|
||
<date>2014-02-26</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Corrected samples to fix validation
|
||
errors.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision>
|
||
<date>2012-08-08</date>
|
||
<revdescription>
|
||
<itemizedlist spacing="compact">
|
||
<listitem>
|
||
<para>Corrected the titles of some
|
||
examples.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</revdescription>
|
||
</revision>
|
||
<revision>
|
||
<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>
|
||
<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?>
|
||
<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">Plug-in</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 plug-in 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>
|