openstack-attic/netconn-api
Code Issues Proposed changes
netconn-api/doc/src/docbkx/quantum-api-2.0/quantum-api-guide.xml
Diane Fleming 3fafe9ccf0 Added new Quantum API v2 book 
Change-Id: I371663d36d06f257d0f42adade9b032f5d6908f3

Adding Quantum API v2 Dev Guide for first time

Change-Id: I0fc3cf80fc6898c7d47f0afcc2bfa9fefb0bd171
2012-08-20 15:53:46 -05:00

2587 lines
119 KiB
XML
Raw Blame History

<?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 role="fo">
<imagedata fileref="figures/Check_mark_23x20_02.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Check_mark_23x20_02.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY ARROW '<inlinemediaobject xmlns="http://docbook.org/ns/docbook">
<imageobject role="fo">
<imagedata fileref="figures/Arrow_east.svg"
format="SVG" scale="60"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/Arrow_east.png"
format="PNG" />
</imageobject>
</inlinemediaobject>'>
<!ENTITY APIv2 'Quantum API v2.0'>
]>
<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 (v2.0)</title>
<titleabbrev>Quantum API v2.0</titleabbrev>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
</author>
<copyright>
<year>2011</year>
<year>2012</year>
<holder>OpenStack</holder>
</copyright>
<releaseinfo>Quantum API v2.0</releaseinfo>
<productname>OpenStack Quantum (virtual network
service)</productname>
<pubdate>2012-08-17</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
who develop applications by using the OpenStack
&APIv2;. </para>
</abstract>
<revhistory>
<revision>
<!-- ... continue addding more revisions here as you change this document using the markup shown below... -->
<date>2012-08-17</date>
<revdescription>
<itemizedlist spacing="compact">
<listitem>
<para>First edition of this book.</para>
</listitem>
</itemizedlist>
</revdescription>
</revision>
</revhistory>
</info>
<xi:include href="ch_preface.xml"/>
<chapter xml:id="Overview-d1e71">
<title>Overview</title>
<para>The Quantum project provides virtual networking services
among devices that are managed by the <link
xlink:href="http://wiki.openstack.org/OpenStack"
>OpenStack</link> compute service. </para>
<para>The &APIv2; combines the <link
xlink:href="http://docs.openstack.org/api/openstack-network/1.0/content/"
>Quantum API v1.1</link> with some essential Internet
Protocol Address Management (IPAM) capabilities from the
<link
xlink:href="http://melange.readthedocs.org/en/latest/apidoc.html"
>Melange API</link>. </para>
<para>These IPAM capabilities enable you to:<itemizedlist>
<listitem>
<para>Associate IP address blocks and other
network configuration settings required by a
network device, such as a default gateway and
dns-servers settings, with a Quantum
network.</para>
</listitem>
<listitem>
<para>Allocate an IP address from a block and
associate it with a device that is attached to
the network through a Quantum port.</para>
</listitem>
</itemizedlist>To do this, the &APIv2; introduces the
subnet entity. A subnet can represent either an IP version
4 or version 6 address block. Each Quantum network
commonly has one or more subnets. When you create a port
on the network, an available fixed IP address is allocated
to it from one the designated subnets for each IP version.
When you delete the port, the allocated addresses return
to the pool of available IPs on the subnet. &APIv2; users
can choose a specific IP address from the block or let
Quantum choose the first available IP address. </para>
<note>
<para>The Quantum API v1.<varname>x</varname> was removed
from the source code tree. To use the Quantum API
v1.<varname>x</varname>, install an earlier
release of Quantum.</para>
</note>
<?hard-pagebreak?>
<section xml:id="Glossary">
<title>Glossary</title>
<informaltable rules="all">
<thead>
<tr>
<td align="left">Term</td>
<td colspan="4" align="left">Description</td>
</tr>
</thead>
<tbody>
<tr>
<td align="left">CRUD</td>
<td colspan="4">In computer programming,
create, read, update, and delete (CRUD)
functions are the basic functions of
persistent storage.</td>
</tr>
<tr>
<td align="left">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 align="left">IPAM</td>
<td colspan="4">Internet Protocol Address
Management (IPAM) is a means of planning,
tracking, and managing the Internet
Protocol (IP) address space that is used
in a network.</td>
</tr>
<tr>
<!-- <td align="left" bgcolor="#4F91BD"> -->
<td align="left">layer-2 network </td>
<!-- <td colspan="4" bgcolor="#4F91BD"> -->
<td colspan="4">A virtual Ethernet network
that is managed by the Quantum service.
Currently, Quantum manages only Ethernet
networks. </td>
</tr>
<tr>
<td align="left">network </td>
<td colspan="4">An isolated virtual layer-2
broadcast domain that is typically
reserved for the tenant who created it
unless the network is configured to be
shared. Tenants can create multiple
networks until they reach the thresholds
specified by per-tenant quotas. </td>
</tr>
<tr>
<!-- <td align="left" bgcolor="#4F91BD"> -->
<td align="left">plugin </td>
<!-- <td colspan="4" bgcolor="#4F91BD"> -->
<td colspan="4">A software component that
implements &APIv2;. </td>
</tr>
<tr>
<td align="left">port </td>
<td colspan="4">A virtual switch port on a
logical network switch. Virtual instances
attach their interfaces into ports. The
logical port also defines the MAC address
and the IP addresses to be assigned to the
interfaces plugged into them. When IP
addresses are associated to a port, this
also implies the port is associated with a
subnet, as the IP address was taken from
the allocation pool for a specific subnet.
</td>
</tr>
<tr>
<td align="left">subnet</td>
<td colspan="4">An IP address block that can
be used to assign IP addresses to virtual
instances. Each subnet must have a CIDR
and must be associated with a network. IPs
can be either selected from the whole
subnet CIDR or from allocation pools that
can be specified by the user. </td>
</tr>
<tr>
<td align="left">VM</td>
<td colspan="4">A virtual machine (VM) is a
completely isolated guest operating system
installation within a normal host
operating system.</td>
</tr>
</tbody>
</informaltable>
</section>
<?hard-pagebreak?>
<section xml:id="Theory">
<title>High-Level Task Flow</title>
<para>The high-level task flow for Quantum networking is
as follows:</para>
<orderedlist>
<listitem>
<para>The tenant creates a network. </para>
<para>For example, the tenant creates the
<literal>net1</literal> network.</para>
</listitem>
<listitem>
<para>The tenant associates a subnet with that
network. </para>
<para>For example, the tenant associates the
<literal>10.0.0.0/24</literal> subnet with
the <literal>net1</literal> network.</para>
</listitem>
<listitem>
<para>The tenant boots a virtual machine (VM) and
specifies a single NIC that connects to the
network. </para>
<para>For
example:<programlisting language="bash" role="gutter: false"><prompt>$</prompt> nova boot --image <emphasis role="italic">image_name</emphasis> --nic net-id=<emphasis role="italic">id_of_net1</emphasis> <emphasis role="italic">server_name</emphasis></programlisting></para>
</listitem>
<listitem>
<para>Nova contacts Quantum and creates the
<literal>port1</literal> port on the
<literal>net1</literal> network.</para>
</listitem>
<listitem>
<para>Quantum assigns an IP address to the
<literal>port1</literal> port.</para>
<note>
<para>Quantum chooses the IP address.</para>
</note>
</listitem>
<listitem>
<para>The tenant deletes the VM. </para>
</listitem>
<listitem>
<para>Nova contacts Quantum and deletes the
<literal>port1</literal> port. </para>
<para>The allocated IP address is returned to the
pool of available IP addresses. </para>
</listitem>
</orderedlist>
</section>
<?hard-pagebreak?>
<section xml:id="plugin">
<title>The Plugin</title>
<para>Virtual networking services are implemented through
a plugin. A plugin can use different techniques and
technologies to provide isolated virtual networks to
tenants. A plugin also provides other services, such
as IP address management. Because each plugin
implements all the operations included in &APIv2;, you
do not need to be concerned about which plugin is
used. </para>
<para>However, some plugins might expose additional
capabilities through API extensions, which are
discussed in this document. For more information about
the extensions exposed by a particular plugin, see the
plugin documentation. </para>
</section>
</chapter>
<chapter xml:id="Concepts-d1e369">
<?dbhtml stop-chunking?>
<title>Concepts</title>
<para>&APIv2; manages the following entities:<itemizedlist>
<listitem>
<para><emphasis role="bold">Network</emphasis>. An
isolated virtual layer-2 domain. A network can
also be a virtual, or logical, switch. See
<xref linkend="Network"/>.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Subnet</emphasis>. An
IP version 4 or version 6 address block from
which IP addresses that are assigned to VMs on
a specified network are selected. See <xref
linkend="subnet"/>.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Port</emphasis>. A
virtual, or logical, switch port on a
specified network. See <xref linkend="Port"
/>.</para>
</listitem>
</itemizedlist></para>
<para>These entities have auto-generated unique identifiers
and support basic create, read, update, and delete (CRUD)
functions with the &POST;, &GET;, &PUT;, and &DELETE;
verbs. </para>
<?hard-pagebreak?>
<section xml:id="Network">
<title>Network</title>
<para>A network is an isolated virtual layer-2 broadcast
domain that is typically reserved for the tenant who
created it unless the network is configured to be
shared. Tenants can create multiple networks until
they reach the thresholds specified by per-tenant
quotas. See <xref linkend="quotas"/>.</para>
<para>In the &APIv2;, the network is the main entity.
Ports and subnets are always associated with a
network. </para>
<?hard-pagebreak?>
<para>The following table describes the attributes for
network objects. </para>
<table rules="all" width="95%">
<caption>Network Attributes</caption>
<col width="20%"/>
<col width="10%"/>
<col width="10%"/>
<col width="10%"/>
<col width="15%"/>
<col width="17%"/>
<col width="20%"/>
<thead>
<tr>
<th>Attribute </th>
<th>Type </th>
<th>Required </th>
<th>CRUD<footnote xml:id="crud">
<para><itemizedlist>
<listitem>
<para><emphasis role="bold"
>C</emphasis>. Use the attribute in
create operations. </para>
</listitem>
<listitem>
<para><emphasis role="bold"
>R</emphasis>. This attribute is
returned in response to show and
list operations. </para>
</listitem>
<listitem>
<para><emphasis role="bold"
>U</emphasis>. You can update the
value of this attribute.</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>D</emphasis>. You can delete the
value of this attribute. </para>
</listitem>
</itemizedlist></para>
</footnote></th>
<th>Default Value </th>
<th>Validation Constraints </th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>id </td>
<td>uuid-str </td>
<td>N/A </td>
<td>R </td>
<td>generated </td>
<td>N/A </td>
<td>UUID for the network. </td>
</tr>
<tr>
<td>name </td>
<td>String </td>
<td>No </td>
<td>CRU </td>
<td>None </td>
<td>N/A </td>
<td>Human-readable name for the network. Might
not be unique. </td>
</tr>
<tr>
<td>admin_state_up </td>
<td>Bool </td>
<td>No </td>
<td>CRU </td>
<td>true </td>
<td>{true|false}</td>
<td>The administrative state of network. If
false (down), the network does not forward
packets.</td>
</tr>
<tr>
<td>status </td>
<td>String </td>
<td>N/A </td>
<td>R </td>
<td>N/A </td>
<td>N/A </td>
<td><para>Indicates whether network is
currently operational. Possible values
include: <itemizedlist>
<listitem>
<para>ACTIVE</para>
</listitem>
<listitem>
<para>DOWN</para>
</listitem>
<listitem>
<para>BUILD</para>
</listitem>
<listitem>
<para>ERROR</para>
</listitem>
</itemizedlist>
</para><para>Plugins might define
additional values. </para></td>
</tr>
<tr>
<td>subnets </td>
<td>list(uuid-str) </td>
<td>No </td>
<td>R </td>
<td>Empty List </td>
<td>N/A </td>
<td>subnets associated with this network.
</td>
</tr>
<tr>
<td>permissions </td>
<td>octal(3) </td>
<td>No </td>
<td>CR<footnote xml:id="group">
<para>The &APIv2; currently ignores
group permissions, and executable
bits. Write access to world, even
if granted by the user, is
currently ignored by the Quantum
API. The full permission mask has
been provided for compatibility
with future implementations.
</para>
</footnote>
</td>
<td>rw- --- --- </td>
<td>3-octal digit string or permission string
in the rwxrwxrwx form.<footnote
xml:id="symbolic">
<para>The &APIv2; also allows the
symbolic string <emphasis
role="italic">private</emphasis>
and <emphasis role="italic"
>public</emphasis> for the
permissions string. Private
corresponds to 0600 or rw- --- ---,
whereas Public corresponds to 0644
or rw-r--r--. </para>
</footnote></td>
<td>Specifies access rights on the network
object for owner, group, and world </td>
</tr>
<tr>
<td>tenant_id </td>
<td>uuid-str </td>
<td>No<footnote xml:id="tenant">
<para>If Quantum is not running with
the Keystone Identity service, the
<literal>tenant_id</literal>
attribute is required. </para>
</footnote>
</td>
<td>CR </td>
<td>N/A </td>
<td>UUID_PATTERN </td>
<td>Owner of network. Only admin users can
specify a tenant_id other than its own.
</td>
</tr>
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="subnet">
<title>Subnet</title>
<para>A subnet represents an IP address block that can be
used to assign IP addresses to virtual instances. Each
subnet must have a CIDR and must be associated with a
network. IPs can be either selected from the whole
subnet CIDR or from allocation pools that can be
specified by the user. </para>
<para>A subnet can also optionally have a gateway, a list
of dns name servers, and host routes. This information
is pushed to instances whose interfaces are associated
with the subnet. </para>
<?hard-pagebreak?>
<table rules="all" width="95%">
<caption>Subnet Attributes</caption>
<col width="20%"/>
<col width="10%"/>
<col width="10%"/>
<col width="10%"/>
<col width="15%"/>
<col width="17%"/>
<col width="20%"/>
<thead>
<tr>
<th>Attribute </th>
<th>Type </th>
<th>Required </th>
<th>CRUD<footnote xml:id="crud2">
<para><itemizedlist>
<listitem>
<para><emphasis role="bold"
>C</emphasis>. Use the attribute in
create operations. </para>
</listitem>
<listitem>
<para><emphasis role="bold"
>R</emphasis>. This attribute is
returned in response to show and
list operations. </para>
</listitem>
<listitem>
<para><emphasis role="bold"
>U</emphasis>. You can update the
value of this attribute.</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>D</emphasis>. You can delete the
value of this attribute. </para>
</listitem>
</itemizedlist></para>
</footnote>
</th>
<th>Default Value </th>
<th>Validation Constraints </th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>id </td>
<td>uuid-str </td>
<td>N/A </td>
<td>R </td>
<td>generated </td>
<td>N/A </td>
<td>UUID representing the subnet </td>
</tr>
<tr>
<td>network_id </td>
<td>uuid-str </td>
<td>Yes </td>
<td>CR </td>
<td>N/A </td>
<td>network this subnet is associated with. </td>
<td/>
</tr>
<tr>
<td>ip_version </td>
<td>int </td>
<td>Yes </td>
<td>CR </td>
<td>4 </td>
<td>{ 4 | 6 } </td>
<td>IP version </td>
</tr>
<tr>
<td>cidr </td>
<td>string </td>
<td>Yes</td>
<td>CR </td>
<td>N/A </td>
<td>valid cidr in the form
&lt;network_address&gt;/&lt;prefix&gt; </td>
<td>cidr representing IP range for this
subnet, based on IP version </td>
</tr>
<tr>
<td>gateway_ip </td>
<td>string </td>
<td>No </td>
<td>CRUD </td>
<td>first address in <emphasis role="italic"
>cidr</emphasis>
</td>
<td>Valid IP address </td>
<td>default gateway used by devices in this
subnet </td>
</tr>
<tr>
<td>dns_nameservers </td>
<td>list(str) </td>
<td>No </td>
<td>CRU </td>
<td>None </td>
<td>No constraint </td>
<td>DNS name servers used by hosts in this
subnet. </td>
</tr>
<tr>
<td>allocation_pools </td>
<td>list(dict) </td>
<td>No </td>
<td>CR </td>
<td>Every address in <emphasis role="italic"
>cidr</emphasis>, excluding <emphasis
role="italic">gateway_ip</emphasis> if
configured </td>
<td>star/end of range must be valid ip </td>
<td>Sub-ranges of cidr available for dynamic
allocation to ports [ { "start":
"10.0.0.2", "end": "10.0.0.254"} ] </td>
</tr>
<tr>
<td>host_routes </td>
<td>list(dict) </td>
<td>No </td>
<td>CRU </td>
<td>default route to gateway_ip </td>
<td>
<emphasis role="italic">TBD</emphasis>
</td>
<td>Routes that should be used by devices with
IPs from this subnet (not including local
subnet route). </td>
</tr>
<tr>
<td>tenant_id </td>
<td>uuid-str </td>
<td>No<footnote xml:id="tenant2">
<para>If Quantum is not running with
the Keystone Identity service, the
<literal>tenant_id</literal>
attribute is required. </para>
</footnote></td>
<td>CR </td>
<td>N/A </td>
<td>UUID_PATTERN </td>
<td>Owner of network. Only admin users can
specify a tenant_id other than its own.
</td>
</tr>
</tbody>
</table>
</section>
<?hard-pagebreak?>
<section xml:id="Port">
<title>Port</title>
<para>A port represents a virtual switch port on a logical
network switch. Virtual instances attach their
interfaces into ports. The logical port also defines
the MAC address and the IP address(es) to be assigned
to the interfaces plugged into them. When IP addresses
are associated to a port, this also implies the port
is associated with a subnet, as the IP address was
taken from the allocation pool for a specific subnet. </para>
<?hard-pagebreak?>
<table rules="all" width="95%">
<caption>Port Attributes</caption>
<col width="20%"/>
<col width="10%"/>
<col width="10%"/>
<col width="10%"/>
<col width="15%"/>
<col width="17%"/>
<col width="20%"/>
<thead>
<tr>
<th>Attribute </th>
<th>Type </th>
<th>Required </th>
<th>CRUD<footnote xml:id="crud3">
<para><itemizedlist>
<listitem>
<para><emphasis role="bold"
>C</emphasis>. Use the attribute in
create operations. </para>
</listitem>
<listitem>
<para><emphasis role="bold"
>R</emphasis>. This attribute is
returned in response to show and
list operations. </para>
</listitem>
<listitem>
<para><emphasis role="bold"
>U</emphasis>. You can update the
value of this attribute.</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>D</emphasis>. You can delete the
value of this attribute. </para>
</listitem>
</itemizedlist></para>
</footnote>
</th>
<th>Default Value </th>
<th>Validation Constraints </th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td>id </td>
<td>uuid-str </td>
<td>N/A </td>
<td>R </td>
<td>generated </td>
<td>N/A </td>
<td>UUID for the port.</td>
</tr>
<tr>
<td>network_id </td>
<td>uuid-str </td>
<td>Yes </td>
<td>CR </td>
<td>N/A </td>
<td>existing network identifier </td>
<td>Network that this port is associated with.
</td>
</tr>
<tr>
<td>admin_state_up </td>
<td>bool </td>
<td>No </td>
<td>CRU </td>
<td>true </td>
<td>{true|false}</td>
<td>Administrative state of port. If false
(down), port does not forward packets.
</td>
</tr>
<tr>
<td>status </td>
<td>string </td>
<td>N/A </td>
<td>R </td>
<td>N/A </td>
<td>N/A </td>
<td><para>Indicates whether network is
currently operational. Possible values
include: <itemizedlist>
<listitem>
<para>ACTIVE</para>
</listitem>
<listitem>
<para>DOWN</para>
</listitem>
<listitem>
<para>BUILD</para>
</listitem>
<listitem>
<para>ERROR</para>
</listitem>
</itemizedlist>
</para><para>Plugins might define
additional values. </para></td>
</tr>
<tr>
<td>mac_address </td>
<td>string </td>
<td>No </td>
<td>CR </td>
<td>generated </td>
<td>valid MAC in 6-octet form separated by
colons </td>
<td>Mac address to use on this port. </td>
</tr>
<tr>
<td>fixed_ips </td>
<td>list(dict) </td>
<td>No </td>
<td>CRU </td>
<td>automatically allocated from pool </td>
<td>Valid IP address and existing subnet
identifier </td>
<td>Specifies IP addresses for the port thus
associating the port itself with the
subnets where the IP addresses are picked
from </td>
</tr>
<tr>
<td>host_routes </td>
<td>list(dict) </td>
<td>No </td>
<td>CR </td>
<td>Empty list </td>
<td>
<emphasis role="italic">TBD</emphasis>
</td>
<td>list of routes to be used with this port.
In case of overlap, overrides routes
specified for the subnets associated with
this port. </td>
</tr>
<tr>
<td>device_id </td>
<td>str </td>
<td>No </td>
<td>CRUD </td>
<td>None </td>
<td>No constraint </td>
<td>identifies the device (e.g., virtual
server) using this port. </td>
</tr>
<tr>
<td>tenant_id </td>
<td>uuid-str </td>
<td>No<footnote xml:id="tenant3">
<para>If Quantum is not running with
the Keystone Identity service, the
<literal>tenant_id</literal>
attribute is required. </para>
</footnote>
</td>
<td>CR </td>
<td>N/A </td>
<td>UUID_PATTERN </td>
<td>Owner of network. Only admin users can
specify a tenant_id other than its own.
</td>
</tr>
</tbody>
</table>
</section>
</chapter>
<chapter xml:id="General_API_Information-d1e436">
<title>General API Information</title>
<para>The &APIv2; is a ReSTful HTTP service that uses all
aspects of the HTTP protocol including methods, URIs,
media types, response codes, and so on. Providers can use
existing features of the protocol including caching,
persistent connections, and content compression. For
example, providers who employ a caching layer can respond
with a <errorcode>203</errorcode> code instead of a
<errorcode>200</errorcode> code when a request is
served from the cache. Additionally, providers can offer
support for conditional &GET; requests by using ETags, or
they may send a redirect in response to a &GET; request.
Create clients so that these differences are accounted
for.</para>
<section xml:id="Authentication-d1e444">
<title>Authentication and Authorization</title>
<para>The &APIv2; uses the <link
xlink:href="https://openstack.keystone.org"
>Keystone Identity Service</link> as the default
authentication service. When Keystone is enabled,
users that submit requests to the Quantum service must
provide an authentication token in <emphasis
role="bold">X-Auth-Token</emphasis> request
header. You obtain the token by authenticating to the
Keystone endpoint. For more information about
Keystone, see the <link
xlink:href="http://docs.openstack.org/api/openstack-identity-service/2.0/content/"
><citetitle>OpenStack Identity Developer
Guide</citetitle></link>. </para>
<para>When Keystone is enabled, the
<literal>tenant_id</literal> attribute is not
required in create requests because the tenant ID is
derived from the authentication token. </para>
<para>The default authorization settings allow only
administrative users to create resources on behalf of
a different tenant. </para>
<para>Quantum uses information received from Keystone to
authorize user requests. Quantum handles the following
types of authorization policies: <itemizedlist>
<listitem>
<para><emphasis role="bold">Operation-based
policies</emphasis></para>
<para>Specify access criteria for specific
operations, possibly with fine-grained
control over specific attributes.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Resource-based
policies</emphasis></para>
<para>Access a specific resource. Permissions
might or might not be granted depending on
the permissions configured for the
resource. Currently available for only the
network resource.</para>
</listitem>
</itemizedlist></para>
<para>The actual authorization policies enforced in
Quantum might vary from deployment to deployment.
</para>
</section>
<?hard-pagebreak?>
<section xml:id="Request_Response_Types">
<title>Request/Response Types</title>
<para>The &APIv2; 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>The <link
xlink:href="http://wiki.openstack.org/OpenStack"
>OpenStack</link> Quantum API supports the
JSON data format. The format for both the request
and the response can be specified either using the
Accept header or adding the .json extension to the
request URI. </para>
<para>Request:</para>
<literallayout class="monospaced">
POST /v1.0/tenants/tenantX/networks HTTP/1.1
Host 127.0.0.1:9696
Content-Type application/json
Accept application/json
Content-Length 57
</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 204
</literallayout>
<programlisting language="json"><xi:include href="samples/networks-post-res.json" parse="text"/></programlisting>
</example>
</section>
<section xml:id="filtering">
<title>Filtering and Column Selection</title>
<para>The &APIv2; supports filtering based on all top
level attributes of a resource. Filters are applicable
to all list requests. </para>
<para>For example, the following request returns all
networks named <literal>foobar</literal>:</para>
<programlisting language="bash" role="gutter: false">GET /v2.0/networks?name=foobar</programlisting>
<para>When you specify multiple filters, the &APIv2;
returns only objects that meet all filtering criteria.
The operation applies an AND condition among the
filters.</para>
<note>
<para>Quantum does not offer an OR mechanism for
filters.</para>
</note>
<para>Alternatively, you can issue a distinct request for
each filter and build a response set from the received
responses on the client-side. </para>
<para>By default, Quantum returns all attributes for any
show or list call. The &APIv2; has a mechanism to
limit the set of attributes returned. For example,
return <literal>id</literal>. </para>
<para>You can use the <literal>field</literal> query
parameter to control the attributes returned from the
&APIv2;. </para>
<para>For example, the following request returns only
<literal>id</literal> and <literal>name</literal>
for each network:</para>
<programlisting language="bash" role="gutter: false">GET /v2.0/networks.json?fields=id&amp;fields=name</programlisting>
</section>
<section xml:id="Async_behaviour">
<title>Synchronous versus Asynchronous Plugin
Behavior</title>
<para>The &APIv2; presents a logical model of network
connectivity consisting of networks, ports, and
subnets. It is up to the Quantum plugin to communicate
with the underlying infrastructure to ensure packet
forwarding is consistent with the logical model. A
plugin might perform these operations asynchronously. </para>
<para>When an API client modifies the logical model by
issuing an HTTP &POST;, &PUT;, or &DELETE; request,
the API call might return before the plugin modifies
underlying virtual and physical switching devices.
However, an API client is guaranteed that all
subsequent API calls properly reflect the changed
logical model. </para>
<para>For example, if a client issues an HTTP &PUT;
request to set the attachment for a port, there is no
guarantee that packets sent by the interface named in
the attachment are forwarded immediately when the HTTP
call returns. However, it is guaranteed that a
subsequent HTTP &GET; request to view the attachment
on that port returns the new attachment value. </para>
<para>You can use the <literal>status</literal> attribute
with the network and port resources to determine
whether the Quantum plugin has successfully completed
the configuration of the resource. </para>
</section>
<section xml:id="bulk_create_operations">
<title>Bulk Create Operations</title>
<para>The &APIv2; enables you to create several objects of
the same type in the same API request. Bulk create
operations use exactly the same API syntax as single
create operations except that you specify a list of
objects rather than a single object in the request
body. </para>
<para>Bulk operations are always performed atomically,
meaning that either all or none of the objects in the
request body are created. If a particular plugin does
not support atomic operations, the &APIv2; emulates
the atomic behavior so that users can expect the same
behavior regardless of the particular plugin running
in the background. </para>
<para>Quantum might be deployed without support for bulk
operations and when the client attempts a bulk create
operation, a <errorcode>400</errorcode>
<errortext>Bad Request</errortext> error is
returned.</para>
<para>For information about how to submit bulk requests to
the &APIv2;, see <xref linkend="bulk_create_networks"
/>, <xref linkend="bulK_create_subnets"/>, and <xref
linkend="bulk_create_ports"/>.</para>
</section>
<section xml:id="quotas">
<title>Quotas</title>
<para>[tbd] Yong to contribute </para>
</section>
<section xml:id="notifications">
<title>Notifications</title>
<para>[tbd] Yong to contribute </para>
</section>
<?hard-pagebreak?>
<section xml:id="extensions">
<title>Extensions</title>
<para>The &APIv2; is extensible. </para>
<para>The purpose of &APIv2; extensions is to: </para>
<itemizedlist>
<listitem>
<para>Introduce new features in the API without
requiring a version change.</para>
</listitem>
<listitem>
<para>Introduce vendor-specific niche
functionality. </para>
</listitem>
<listitem>
<para>Act as a proving ground for experimental
functionalities that might be included in a
future version of the API. </para>
</listitem>
</itemizedlist>
<para>To programmatically determine which extensions are
available, issue a &GET; request on the
<command>v2.0/extensions</command> URI. </para>
<para>To query extensions individually by unique alias,
issue a &GET; request on the
<command>/v2.0/extensions/<replaceable>alias_name</replaceable></command>
URI. Use this method to easily determine if an
extension is available. If the extension is not
available, a <errorcode>404</errorcode>
<errortext>itemNotFound</errortext> response is
returned. </para>
<para>You can extend existing core API resources with new
actions or extra attributes. Also, you can add new
resources as extensions. Extensions usually have tags
that prevent conflicts with other extensions that
define attributes or resources with the same names,
and with core resources and attributes. Because an
extension might not be supported by all plugins, the
availability of an extension varies with deployments
and the specific plugin in use. </para>
</section>
<?hard-pagebreak?>
<section xml:id="faults">
<title>Faults</title>
<para>The &APIv2; returns an error response if a failure
occurs while processing a request. Quantum uses only
standard HTTP error codes. 4<varname>xx</varname>
errors indicate problems in the particular request
being sent from the client. <informaltable rules="all">
<col width="10%"/>
<col width="20%"/>
<col width="70%"/>
<thead>
<tr>
<th>Error</th>
<th colspan="2">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td rowspan="4">400 </td>
<td rowspan="4">Bad Request</td>
<td>Malformed request URI or body</td>
</tr>
<tr>
<td>Requested admin state invalid</td>
</tr>
<tr>
<td>Invalid values entered</td>
</tr>
<tr>
<td>Bulk operations disallowed</td>
</tr>
<tr>
<td rowspan="2">404 </td>
<td rowspan="2">Not Found</td>
<td>Non existent URI</td>
</tr>
<tr>
<td>Resource not found</td>
</tr>
<tr>
<td rowspan="3">409</td>
<td rowspan="3">Conflict</td>
<td>Port configured on network</td>
</tr>
<tr>
<td>IP allocated on subnet</td>
</tr>
<tr>
<td>Conflicting IP allocation pools for
subnet</td>
</tr>
<tr>
<td rowspan="2">422</td>
<td rowspan="2">Unprocessable Entity</td>
<td>Validation failed</td>
</tr>
<tr>
<td>Method not allowed for request body
(such as trying to update attributes
that can be specified at create-time
only)</td>
</tr>
<tr>
<td>500</td>
<td>Internal server error</td>
<td>Internal Quantum error</td>
</tr>
<tr>
<td>503</td>
<td>Service unavailable</td>
<td>Failure in Mac address generation</td>
</tr>
</tbody>
</informaltable></para>
<para>Users submitting requests to the &APIv2; might also
receive the following errors: </para>
<itemizedlist>
<listitem>
<para><errorcode>401</errorcode> Unauthorized.
Credentials that were not valid were provided. </para>
<para>if invalid credentials are provided </para>
</listitem>
<listitem>
<para><errorcode>403</errorcode> Forbidden - If
the user cannot access a specific resource or
perform the requested operation. </para>
</listitem>
</itemizedlist>
</section>
</chapter>
<chapter xml:id="API_Operations">
<title>API Operations</title>
<section xml:id="Networks">
<title>Networks</title>
<para>Use the &APIv2; to manage network resources. </para>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr align="center">
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/networks</td>
<td>Lists a summary of all networks defined in
Quantum that are accessible to the tenant
who submits the request.</td>
</tr>
<tr>
<td>&GET;</td>
<td>/networks/<parameter>network_id</parameter></td>
<td>Lists detailed information for the
specified network ID.</td>
</tr>
<tr>
<td>&POST;</td>
<td>/networks</td>
<td>Creates a new Quantum network.</td>
</tr>
<tr>
<td>&PUT;</td>
<td>/networks/<parameter>network-id</parameter></td>
<td>Updates the specified network.</td>
</tr>
<tr>
<td>&DELETE;</td>
<td>/networks/<parameter>network-id</parameter></td>
<td>Destroys the specified network and all
associated resources.</td>
</tr>
</tbody>
</informaltable>
<?hard-pagebreak?>
<section xml:id="List_Networks">
<title>List Networks</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/networks</td>
<td>Lists a summary of all networks
defined in Quantum that are accessible
to the tenant who submits the request.
</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>)</simpara>
<para>Lists a summary of all networks defined in
Quantum that are accessible to the tenant who
submits the request. The list provides the unique
ID for each network. </para>
<para>This operation does not require a request body,
unless the Quantum server is running without
Keystone integration. </para>
<para>This operation returns a response body.</para>
<!-- <example>
<title>List Networks: XML Request</title>
<literallayout class="monospaced">GET /tenants/XYZ/networks.xml </literallayout>
</example>
<example>
<title>List Networks: XML Response</title>
<programlisting language="xml"><xi:include href="samples/networks-get-res.xml" parse="text"/></programlisting>
</example>
<?hard-pagebreak?>-->
<example>
<title>List Networks: JSON Request</title>
<literallayout class="monospaced">
GET /v2.0/networks
Accept: application/json
</literallayout>
</example>
<example>
<title>List Networks: JSON Response</title>
<programlisting language="json"><xi:include href="samples/networks-get-res.json" parse="text"/></programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="List_Networks_Detail">
<title>Show Network</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/networks/<parameter>network_id</parameter></td>
<td>Lists detailed information for the
specified network ID.</td>
</tr>
</tbody>
</informaltable>
<simpara> Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara> Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Not Found
(<errorcode>404</errorcode>)</simpara>
<para>This operation returns the status, subnets,
name, admin state, tenant ID, and ID for the
specified network ID. </para>
<para>This operation does not require a request
body.</para>
<para>This operation returns a response body.</para>
<!-- <example>
<title>Networks List Request/Response
(XML)</title>
<para>Request:</para>
<literallayout class="monospaced">GET /tenants/XYZ/networks/detail.xml </literallayout>
<para>Response:</para>
<programlisting language="xml"><xi:include href="samples/networks-get-detail-res.xml" parse="text"/>
</programlisting>
</example>
<?hard-pagebreak?> -->
<example>
<title>Show Network: JSON Request</title>
<literallayout class="monospaced">
GET /v2.0/networks/afc75773-640e-403c-9fff-62ba98db1f19
Accept: application/json
</literallayout>
</example>
<example>
<title>Show Network: JSON Response</title>
<programlisting language="json"><xi:include href="samples/networks-get-detail-res.json" parse="text"/> </programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Create_Network">
<title>Create Network</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&POST;</td>
<td>/networks</td>
<td>Creates a new Quantum network.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>) Unauthorized
(<errorcode>401</errorcode>)</simpara>
<para>This operation requires a request body. The
request body must contain a
<literal>network</literal> object that
specifies a symbolic name for the network. </para>
<para>This operation returns a response body.</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: JSON Request</title>
<literallayout class="monospaced">
POST v2.0/networks.json
Content-Type: application/json
Accept: application/json
</literallayout>
<programlisting language="json"><xi:include href="samples/network-post-req.json" parse="text"/> </programlisting>
</example>
<example>
<title>Create Network: JSON Response</title>
<programlisting language="json"><xi:include href="samples/network-post-res.json" parse="text"/> </programlisting>
</example>
<section xml:id="bulk_create_networks">
<title>Bulk Create Networks</title>
<para>This operation enables you to create several
networks in a single request. </para>
<para>This operation requires a request
body.</para>
<para>This operation returns a response body. </para>
<para>Specify a list of networks in the request
body, as shown in the following example: </para>
<example>
<title>Bulk Create Servers: JSON Request </title>
<literallayout class="monospaced">
POST v2.0/networks.json
Content-Type: application/json
Accept: application/json
</literallayout>
<programlisting language="json">{
"networks": [
{
"name": "sample_network_1",
"admin_state_up": false
},
{
"name": "sample_network_2",
"admin_state_up": false
}]
}</programlisting>
</example>
<para>The bulk create operation is always atomic.
Either all or no networks in the request body
are created. </para>
<note>
<para>You can use the
<literal>permissions</literal>
attribute to create a public network. A
public network can be shared with other
tenants. This attribute enables you to
specify file system-like permissions on
Quantum resources. However, &APIv2;
currently supports creating networks that
are shared with every other tenant. To do
so, set the <literal>permissions</literal>
attribute to <literal>0644</literal> or
<literal>rw- r-- r--</literal>. </para>
<para>Control of the
<literal>permissions</literal>
attribute could reserved to only specific
users, such as administrators. In this
case, regular users who try to create a
network with a permissions setting that is
different from the default value receive a
<errorcode>403</errorcode>
<errortext>Forbidden</errortext> error.
</para>
</note>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="Update_Network">
<title>Update Network</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&PUT;</td>
<td>/networks/<parameter>network-id</parameter></td>
<td>Updates the specified network.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>) Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>) Not Found
(<errorcode>404</errorcode>), Unprocessable
Entity (<errorcode>422</errorcode>)</simpara>
<para/>
<para>This operation requires a request body. You can
set the following attributes in the request
body:<table rules="all">
<caption>Update Network Request Body
Attributes</caption>
<col width="25%"/>
<col width="75%"/>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>The name for the network.</td>
</tr>
<tr>
<td>admin_state_up</td>
<td>Specifies whether the admin state
is up or down. Set to
<literal>true</literal> for up and
<literal>false</literal> for down.
If down, the network does not
forward packets.</td>
</tr>
</tbody>
</table></para>
<para>You cannot update the <literal>status</literal>,
<literal>tenant_id</literal>, or
<literal>id</literal> attributes. If you try
to update these attributes, a
<errorcode>422</errorcode>
<errortext>Unprocessable Entity</errortext> error
is returned. </para>
<para>This operation returns a response body.</para>
<note>
<para>Update operations in Quantum adopt patch
semantics. This implies that the &APIv2; does
not require the user to send the whole
resource to be updated, but just the
attributes that the user wishes to update, as
shown in the following example. </para>
</note>
<!-- <example>
<title>Update Network Request/Response
(XML)</title>
<para>Request:</para>
<literallayout class="monospaced">PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml </literallayout>
<programlisting language="xml"><xi:include href="samples/network-post-req.xml" parse="text"/> </programlisting>
<para>Response:</para>
<para><emphasis>No data is returned in the
response body.</emphasis></para>
</example> -->
<example>
<title>Update Network: JSON Request </title>
<literallayout class="monospaced">
PUT /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766.json
Content-Type: application/json
Accept: application/json
</literallayout>
<programlisting language="json">{
"network":
{
"name": "updated_name"
}
}</programlisting>
</example>
<example>
<title>Update Network: JSON Response</title>
<programlisting language="json">status: 200
content-length: 192
content-type: application/json
{
"network":
{
"status": "ACTIVE",
"subnets": [],
"name": "updated_name",
"admin_state_up": false,
"shared": false,
"tenant_id": "c1210485b2424d48804aad5d39c61b8f",
"id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766"
}
} </programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Delete_Network">
<title>Delete Network</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&DELETE;</td>
<td>/networks/<parameter>network-id</parameter></td>
<td>Deletes the specified network and all
associated resources.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>204</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>) Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>), Not Found
(<errorcode>404</errorcode>), Network In Use
(<errorcode>409</errorcode>) </simpara>
<para>This operation deletes a Quantum network and its
associated subnets provided that no port is
currently configured on the network. </para>
<para>If ports are still configured on the network
that you want to delete, a
<errorcode>409</errorcode>
<errortext>Network In Use</errortext> error is
returned. </para>
<para>This operation does not require a request body. </para>
<para>This operation does not return a response
body.</para>
<!-- <example>
<title>Delete Network Request/Response
(XML)</title>
<para>Request:</para>
<literallayout class="monospaced">DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml </literallayout>
<para>Response:</para>
<para><emphasis>No data is returned in the
response body.</emphasis></para>
</example> -->
<example>
<title>Delete Network: JSON Request </title>
<literallayout class="monospaced">DELETE /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766
Content-Type: application/json
Accept: application/json </literallayout>
</example>
<example>
<title>Delete Network: JSON Response </title>
<literallayout class="monospaced">status: 204</literallayout>
</example>
</section>
</section>
<section xml:id="Subnets">
<title>Subnets</title>
<para>Use the &APIv2; to manage subnet resources. </para>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr align="center">
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/subnets</td>
<td>Lists all subnets that are accessible to
the tenant who submits the request.</td>
</tr>
<tr>
<td>&GET;</td>
<td>/subnets/<parameter>subnet_id</parameter></td>
<td>Lists detailed information for the
specified subnet.</td>
</tr>
<tr>
<td>&POST;</td>
<td>/subnets</td>
<td>Creates a subnet on the specified
network.</td>
</tr>
<tr>
<td>&PUT;</td>
<td>/subnets/<parameter>subnet-id</parameter></td>
<td>Updates the specified subnet.</td>
</tr>
<tr>
<td>&DELETE;</td>
<td>/subnets/<parameter>subnet-id</parameter></td>
<td>Removes the specified subnet.</td>
</tr>
</tbody>
</informaltable>
<?hard-pagebreak?>
<section xml:id="list_subnets">
<title>List Subnets</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/subnets</td>
<td>Lists all subnets that are accessible
to the tenant who submits the
request.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Unauthorized
(<errorcode>401</errorcode>) </simpara>
<para>This operation returns a list of subnets objects
the tenant has access to. Default policy settings
returns exclusively subnets owned by the tenant
submitting the request, unless the request is
submitted by an user with administrative rights.
You can control which attributes are returned by
using the <emphasis role="italic"
>fields</emphasis> query parameter. You can
filter results by using query string parameters.
See <xref linkend="filtering"/>. </para>
<para>This operation does not require a request
body.</para>
<para>This operation returns a response 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>List Subnets: JSON Request </title>
<literallayout class="monospaced">GET v2.0/subnets.json
Accept: application/json </literallayout>
</example>
<example>
<title>List Subnets: JSON Response</title>
<programlisting language="json"><xi:include href="samples/subnets_get_resp.json" parse="text"/> </programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="show_subnet">
<title>Show Subnet</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/subnets/<parameter>subnet-id</parameter></td>
<td>Gets information about a specified
subnet.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Not Found
(<errorcode>404</errorcode>) </simpara>
<para>This operation returns data about the subnet
specified in the request URI. You can control
which attributes are returned by using the
<emphasis role="italic">fields</emphasis>
query parameter, as discussed in <xref
linkend="filtering"/>. </para>
<para>This operation does not require a request
body.</para>
<para>This operation returns a response 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>Show Subnet: JSON Request</title>
<literallayout class="monospaced">GET /v2.0/subnets/4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861
Accept: application/json</literallayout>
</example>
<example>
<title>Show Subnet: JSON Response</title>
<literallayout class="monospaced">status: 200
content-length: 309
content-type: application/json </literallayout>
<programlisting language="json"><xi:include href="samples/subnets-get-detail-res.json" parse="text"/> </programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="create_subnet">
<title>Create Subnet</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&POST;</td>
<td>/subnets</td>
<td>Creates a subnet on the specified
network.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code: Created
(<returnvalue>201</returnvalue>) </simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>), Not Found
(<errorcode>404</errorcode>)</simpara>
<para>This operation creates a new subnet on the
specified network. The network ID,
<parameter>network_id</parameter>, is
required. You must also specify the
<literal>cidr</literal> attribute for the
subnet, in the form:
<programlisting><parameter>network_address</parameter>/<parameter>prefix</parameter></programlisting>The
remaining attributes are optional. </para>
<para>By default, Quantum creates IP v4 subnets. To
create an IP v6 subnet, you must specify the value
<literal>6</literal> for the
<parameter>ip_version</parameter> attribute in
the request body. Quantum does not try to derive
the correct IP version from the provided CIDR. If
the parameter for the gateway address,
<parameter>gateway_ip</parameter>, is not
specified, Quantum allocates an address from the
cidr for the gateway for the subnet. </para>
<para>To specify a subnet without a gateway, specify
the value <literal>none</literal> for the
<literal>gateway_ip</literal> attribute in the
request body. If allocation pools attribute,
<literal>allocation_pools</literal>, is not
specified, Quantum automatically allocates pools
for covering all IP addresses in the CIDR,
excluding the address reserved for the subnet
gateway. Otherwise, you can explicitly specify
allocation pools as shown in the following
example. </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 Subnet: JSON Request</title>
<literallayout class="monospaced">
POST /v2.0/subnets
Content-Type: application/json
Accept: application/json
</literallayout>
<programlisting language="json">{
"subnet": {
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"ip_version": 4,
"cidr": "10.0.3.0/24",
"allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}]
}
} </programlisting>
</example>
<example>
<title>Create Subnet: JSON Response</title>
<programlisting language="json"><xi:include href="samples/subnet-post-req.json" parse="text"/> </programlisting>
</example>
<section xml:id="bulK_create_subnets">
<title>Bulk Create Subnets</title>
<para>This operation requires a request
body.</para>
<para>This operation returns a response
body.</para>
<para>This operation enables you to create several
subnets in a single request. Specify a list of
subnets in the request body, as shown in the
following example: </para>
<example>
<title>Bulk Create Subnets: JSON Request </title>
<literallayout class="monospaced">
POST /v2.0/subnets
Content-Type: application/json
Accept: application/json
</literallayout>
<programlisting language="json">{
"subnets": [
{
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"ip_version": 4,
"cidr": "10.0.4.0/24",
}
{
"network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc",
"ip_version": 4,
"cidr": "10.0.5.0/24",
}
]
}</programlisting>
</example>
<para>The bulk create operation is always atomic.
Either all subnets or no subnets in the
request body are created. </para>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="update_subnet">
<title>Update Subnet</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&PUT;</td>
<td>/subnets/<parameter>subnet-id</parameter></td>
<td>Updates the specified subnet.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code: Ok
(<returnvalue>200</returnvalue>)</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>), Not Found
(<errorcode>404</errorcode>), Unprocessable
Entity (<errorcode>422</errorcode>) </simpara>
<para>This operation updates the specified subnet.
Some attributes, such as IP version
(<parameter>ip_version</parameter>), CIDR
(<parameter>cidr</parameter>), and IP
allocation pools
(<parameter>allocation_pools</parameter>)
cannot be updated. Attempting to update these
attributes results in a <errorcode>422</errorcode>
<errortext>Unprocessable Entity</errortext> error. </para>
<para>This operation requires a request body.</para>
<para>This operation returns a response body.</para>
<note>
<para>Update operations in Quantum adopt patch
semantics. This implies that the &APIv2; does
not require you to send the whole resource to
be updated, but just the attributes that you
wish to update, as shown in the following
example. </para>
</note>
<!-- <example>
<title>Set Port State Request/Response
(XML)</title>
<para>Request:</para>
<literallayout class="monospaced">PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml </literallayout>
<programlisting language="xml"><xi:include href="samples/port-post-req.xml" parse="text"/>
</programlisting>
<para>Response:</para>
<para><emphasis>No data is returned in the
response body..</emphasis></para>-->
<example>
<title>Update Subnet: JSON Request</title>
<literallayout class="monospaced">
PUT /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031
Content-Type: application/json
Accept: application/json
</literallayout>
<programlisting language="json">{
"subnet":
{
"gateway_ip": "10.0.3.254",
"name": "new_name"
}
}</programlisting>
</example>
<example>
<title>Update Subnet: JSON Response</title>
<programlisting language="json"><xi:include href="samples/subnet-post-res.json" parse="text"/></programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="delete_subnet">
<title>Delete Subnet</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&DELETE;</td>
<td>/subnets/<parameter>subnet-id</parameter></td>
<td>Removes the specified subnet.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>204</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>), Not Found
(<errorcode>404</errorcode>), Conflict
(<errorcode>409</errorcode>)</simpara>
<simpara>This operation removes a subnet from a
Quantum network. The operation fails if IP
addresses from the subnet that you want to delete
are still allocated. </simpara>
<para>This operation does not require a request
body.</para>
<para>This operation does not return a response
body.</para>
<!-- <example>
<title>Delete Port State Request/Response
(XML)</title>
<para>Request:</para>
<literallayout class="monospaced">DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml </literallayout>
<para>Response:</para>
<para><emphasis>No data is returned in the
response body..</emphasis></para>
</example> -->
<example>
<title>Delete Subnet: JSON Request</title>
<literallayout class="monospaced">
DELETE /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031
Accept: application/json
</literallayout>
</example>
<example>
<title>Delete Subnet: Response </title>
<literallayout class="monospaced">Status: 204</literallayout>
</example>
</section>
</section>
<section xml:id="Ports">
<title>Ports</title>
<para>Use the &APIv2; to manage port resources. </para>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr align="center">
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/ports</td>
<td>Lists all ports to which the tenant has
access.</td>
</tr>
<tr>
<td>&GET;</td>
<td>/ports/<parameter>port_id</parameter></td>
<td>Shows information for the specified
port.</td>
</tr>
<tr>
<td>&POST;</td>
<td>/ports</td>
<td>Creates a new port for the specified
network.</td>
</tr>
<tr>
<td>&PUT;</td>
<td>/ports/<parameter>port-id</parameter></td>
<td>Updates the specified port.</td>
</tr>
<tr>
<td>&DELETE;</td>
<td>/ports/<parameter>port-id</parameter></td>
<td>Removes the specified port.</td>
</tr>
</tbody>
</informaltable>
<?hard-pagebreak?>
<section xml:id="List_Ports">
<title>List Ports</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/ports</td>
<td> Lists all ports to which the tenant
has access.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Unauthorized
(<errorcode>401</errorcode>)</simpara>
<para>This operation returns a list of ports to which
the tenant has access. Default policy settings
return only those subnets that are owned by the
tenant who submits the request, unless the request
is submitted by an user with administrative
rights. Users can control which attributes should
be returned by using the
<parameter>fields</parameter> query parameter.
Additionally, you can filter results by using
query string parameters. </para>
<para>This operation does not require a request body. </para>
<para>This operation returns a response 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>List Ports: JSON Request</title>
<literallayout class="monospaced">
GET /v2.0/ports.json HTTP/1.1
content-type: application/json
accept: application/json
</literallayout>
<para>Response:</para>
<programlisting language="json"><xi:include href="samples/ports-get-res.json" parse="text"/> </programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Show_port">
<title>Show Port</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&GET;</td>
<td>/ports/<parameter>port-id</parameter></td>
<td>Shows information for the specified
port.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Not Found
(<errorcode>404</errorcode>)</simpara>
<para>This operation returns information for the port
specified in the request URI. </para>
<para>This operation does not require a request
body.</para>
<para>This operation returns a response 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: JSON Request</title>
<para>
<programlisting>
GET /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json
accept: application/json
</programlisting>
</para>
<para>Response:</para>
<programlisting language="json"><xi:include href="samples/port-get-res.json" parse="text"/> </programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Create_Port">
<title>Create Port</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&POST;</td>
<td>/ports</td>
<td>Creates a port on the specified
network.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>201</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>), Not Found
(<errorcode>404</errorcode>), Conflict
(<errorcode>409</errorcode>) </simpara>
<para>This operation creates a new Quantum port. The
network where the port is created must be
specified in the <parameter>network_id</parameter>
attribute in the request body. You can also
specify the following optional attributes: </para>
<itemizedlist>
<listitem>
<para>A symbolic name for the port </para>
</listitem>
<listitem>
<para>MAC address </para>
</listitem>
<listitem>
<para>Administrative state. Set to
<literal>true</literal> for up, and
<literal>false</literal> for down.
</para>
</listitem>
<listitem>
<para>Fixed IPs <itemizedlist>
<listitem>
<para>If you specify just a subnet
ID, Quantum allocates the first
available IP from that subnet to
the port.</para>
</listitem>
<listitem>
<para>If you specify both a subnet
ID and an IP address, Quantum tries
to allocate the specified address
to the port.</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>Host routes for the port, in addition to
the host routes defined for the subnets
that the port is associated with.</para>
</listitem>
</itemizedlist>
<!-- <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> -->
<para>This operation requires a request body.</para>
<para>This operation returns a response body.</para>
<example>
<title>Create Port: JSON Request</title>
<literallayout class="monospaced">POST /v2.0/ports.json HTTP/1.1
Content-Length: 158
content-type: application/json
accept: application/json</literallayout>
<programlisting language="json"><xi:include href="samples/port-post-req.json" parse="text"/></programlisting>
</example>
<example>
<title>Create Port: JSON Response</title>
<programlisting language="json"><xi:include href="samples/port-post-res.json" parse="text"/></programlisting>
</example>
<section xml:id="bulk_create_ports">
<title>Bulk Create Port</title>
<para>This operation requires a request
body.</para>
<para>This operation returns a response
body.</para>
<para>This operation enables you to create several
ports in a single request. Specify a list of
ports in the request body. </para>
<example>
<title>Bulk Create Port: JSON Request</title>
<programlisting>xx</programlisting>
</example>
<para>The &APIv2; always guarantees the atomic
completion of the bulk operation. </para>
</section>
</section>
<?hard-pagebreak?>
<section xml:id="Update_Port">
<title>Update Port</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&PUT;</td>
<td>/ports/<parameter>port-id</parameter></td>
<td>Updates the specified port.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>200</returnvalue>
</simpara>
<simpara>Error Response Codes: Bad Request
(<errorcode>400</errorcode>), Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>), Not Found
(<errorcode>404</errorcode>), Conflict
(<errorcode>409</errorcode>), Unprocessable
Entity (<errorcode>422</errorcode>)</simpara>
<para>You can use this operation to update information
for a port, such as its symbolic name and
associated IPs. When you update IPs for a port,
the previously associated IPs are removed,
returned to the respective subnets allocation
pools, and replaced by the IPs specified in the
body for the update request. Therefore, this
operation replaces the
<parameter>fixed_ip</parameter> attribute when
it is specified in the request body. If the new IP
addresses are not valid, for example, they are
already in use, the operation fails and the
existing IP addresses are not removed from the
port. </para>
<!-- <example>
<title>Set Port State Request/Response
(XML)</title>
<para>Request:</para>
<literallayout class="monospaced">PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml </literallayout>
<programlisting language="xml"><xi:include href="samples/port-post-req.xml" parse="text"/>
</programlisting>
<para>Response:</para>
<para><emphasis>No data is returned in the
response body..</emphasis></para>
</example> -->
<para>This operation requires a request body.</para>
<para>This operation returns a response body.</para>
<example>
<title>Update Port: JSON Request</title>
<literallayout class="monospaced">PUT /v2.0/ports/1d8591f4-7b62-428e-857d-e82a15e5a7f1.json HTTP/1.1
Content-Length: 63
content-type: application/json
accept: application/json </literallayout>
<programlisting language="json">{
"port": {
"device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63"
}
}</programlisting>
</example>
<example>
<title>Update Port: JSON Response</title>
<programlisting language="json">Status: 200
Content-Type: application/json;
Content-Length: 410
{
"port": {
"admin_state_up": true,
"device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63",
"fixed_ips": [
{
"ip_address": "192.168.111.4",
"subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27"
}
],
"id": "1d8591f4-7b62-428e-857d-e82a15e5a7f1",
"mac_address": "fa:16:3e:70:d2:8c",
"name": "port2",
"network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12",
"status": "ACTIVE",
"tenant_id": "cf1a5775e766426cb1968766d0191908"
}
}</programlisting>
</example>
</section>
<?hard-pagebreak?>
<section xml:id="Delete_Port">
<title>Delete Port</title>
<informaltable rules="all" width="100%">
<col width="20%"/>
<col width="20%"/>
<col width="60%"/>
<thead>
<tr>
<td>Verb</td>
<td>URI</td>
<td>Description</td>
</tr>
</thead>
<tbody>
<tr>
<td>&DELETE;</td>
<td>/ports/<parameter>port-id</parameter></td>
<td>Removes the specified port.</td>
</tr>
</tbody>
</informaltable>
<simpara>Normal Response Code:
<returnvalue>204</returnvalue>
</simpara>
<simpara>Error Response Codes: Unauthorized
(<errorcode>401</errorcode>), Forbidden
(<errorcode>403</errorcode>), Not Found
(<errorcode>404</errorcode>)</simpara>
<para>This operation removes a port from a Quantum
network. If IP addresses are associated with the
port, they are returned to the respective subnets
allocation pools. </para>
<para>This operation does not require a request
body.</para>
<para>This operation does not return a response
body.</para>
<!-- <example>
<title>Delete Port State Request/Response
(XML)</title>
<para>Request:</para>
<literallayout class="monospaced">DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml </literallayout>
<para>Response:</para>
<para><emphasis>No data is returned in the
response body..</emphasis></para>
</example> -->
<example>
<title>Delete Port: JSON Request</title>
<literallayout class="monospaced"> DELETE /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json
accept: application/json </literallayout>
</example>
<example>
<title>Delete Port: JSON Response</title>
<literallayout class="monospaced"> status: 204 </literallayout>
</example>
</section>
</section>
</chapter>
</book>
View Git Blame Copy Permalink