openstack-attic
/
netconn-api
Code Issues Proposed changes
netconn-api/v1.0/neutron-api-guide.xml

1859 lines
95 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book [
<!-- Some useful entities borrowed from HTML -->
<!ENTITY ndash "&#x2013;">
<!ENTITY mdash "&#x2014;">
<!ENTITY hellip "&#x2026;">
<!ENTITY plusmn "&#xB1;">
<!-- 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 &mdash; 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&mdash;for example, a stack trace&mdash;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>
View Git Blame Copy Permalink