openstack-attic/netconn-api
Code Issues Proposed changes
fae0946ffb
netconn-api/v1.0/neutron-api-guide.xml
annegentle 88e5f87f97 Rebuild 1.0 so that JSON fixes are picked up 
- I believe there could still be clouds running that API

Change-Id: If08c12b65fe02d6f4973b492a6caef472bf64d89
Partial-Bug: 1283715
2014-05-01 18:41:30 +02:00

1828 lines
97 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="openstack-networking-v1.0-api-spec">
<title>OpenStack Networking API Guide (1.0)</title>
<?rax pdf.url="../netconn-api-guide-1.0.pdf"?>
<titleabbrev>OpenStack Networking 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>Networking API v1.0</releaseinfo>
<productname>OpenStack Networking (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 Networking
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>OpenStack Networking is a project to provide "network connectivity
as a service" between devices managed by the OpenStack compute
service. For more information on OpenStack Networking and the other
network-related projects please check the OpenStack Networking home
page (<link xlink:href="http://wiki.openstack.org/Neutron"/>) 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/neutron"
>bugs.launchpad.net/neutron</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 OpenStack Networking API. To
use the information provided here, you should first have a
general understanding of the OpenStack 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 OpenStack Networking
distribution:</para>
<itemizedlist spacing="compact">
<listitem>
<para>Openvswitch - Implementing OpenStack Networking API
with Open vSwitch</para>
</listitem>
<listitem>
<para>Cisco - Implementing OpenStack Networking 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
OpenStack Networking. An entity can use OpenStack
Networking 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 OpenStack Networking service. For the time
being, OpenStack Networking 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 OpenStack
Networking 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 OpenStack Networking
APIs.</td>
</tr>
<tr>
<td align="center">Port</td>
<td colspan="4">A port on the virtual network switch
represented by a OpenStack Networking 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 OpenStack Networking 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 OpenStack
Networking’s logical model.</para>
<para>OpenStack Networking abstracts the physical implementation of
the network, allowing plugins to configure and manage physical
resources. OpenStack Networking is a standalone service, in that
it requires no other project within OpenStack to function
correctly.</para>
<para>Further OpenStack Networking is agnostic to the entities it
allows to connect. While we anticipate Nova instances will be a
heavy user of OpenStack Networking, any entity can make use of
any OpenStack Networking created network so long as it provides
an appropriate interfaces for exposing VIFs to OpenStack
Networking 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
OpenStack Networking is used for building OpenStack networks,
VIFs would be created, owned, and managed in Nova. VIFs are
connected to OpenStack Networking networks via ports. A port is
analogous to a port on a network switch, and it has an
administrative state. OpenStack Networking 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 OpenStack Networking API
creates an attachment object, which specifies the fact that a
VIF with a given identifier is plugged into the port.</para>
<para>The OpenStack Networking plugin is responsible for managing
virtual and/or physical network switches to implement the
network forwarding connectivity described by the OpenStack
Networking 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 OpenStack Networking 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 OpenStack Networking, 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 Networking 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 Networking service does
not require that each request will include the credentials of
the user submitting the request.</para>
<para>However, OpenStack Networking deployments can support several
authentication schemes (OAuth, Basic Auth, Token). The
authentication scheme used is determined by the provider of the
OpenStack Networking 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
OpenStack Networking pipeline (available in <code>etc/OpenStack
Networking.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 Networking 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 Networking API should be prefixed with
the API version identifier and the tenant identifier, as
follows:</para>
<para>
<code>/{OpenStack
Networking-version}/tenants/{tenant-id}/{OpenStack
Networking-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 Networking 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 OpenStack Networking Plugins</title>
<para>The OpenStack Networking API presents a logical model of
network connectivity consisting of networks, ports, and
attachments. It is up to the OpenStack Networking 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 OpenStack Networking
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 OpenStack Networking 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 OpenStack Networking
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 OpenStack Networking 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 OpenStack
Networking 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 OpenStack Networking 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
OpenStack Networking 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 OpenStack
Networking 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 OpenStack Networking 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 OpenStack Networking 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 OpenStack Networking 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 OpenStack
Networking 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 OpenStack Networking; 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 OpenStack Networking.</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 OpenStack
Networking based on the information provided in the request
body.</para>
<para>OpenStack Networking 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 OpenStack Networking 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
OpenStack Networking 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 OpenStack Networking 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. OpenStack Networking 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 OpenStack
Networking 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 OpenStack Networking 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 OpenStack Networking
network based on the information provided in the request
body. OpenStack Networking 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 OpenStack Networking 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 OpenStack Networking
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 OpenStack
Networking 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>OpenStack Networking 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