<?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>'>
]>
<book xmlns="http://docbook.org/ns/docbook"
      xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns:xi="http://www.w3.org/2001/XInclude"
      xmlns:svg="http://www.w3.org/2000/svg"
      xmlns:m="http://www.w3.org/1998/Math/MathML"
      xmlns:html="http://www.w3.org/1999/xhtml"
      xmlns:db="http://docbook.org/ns/docbook"
      version="5.0" status="final"
    xml:id="Quantum-api-spec">
    <title>Quantum API Guide (1.0)</title>
    <titleabbrev>Quantum API 1.0</titleabbrev>
    <info>
        <author>
            <personname>
                <firstname/>
                <surname/>
            </personname>
        </author>
        <copyright>
            <year>2011</year>
            <holder>OpenStack</holder>
        </copyright>
        <releaseinfo>Quantum API v1.0</releaseinfo>
        <productname>OpenStack Quantum (virtual network service)</productname>
        <pubdate>2011-09-22</pubdate>
        <legalnotice role="apache2">
            <annotation>
                <remark>Copyright details are filled in by the template.</remark>
            </annotation>
        </legalnotice>
        <abstract>
            <para>This document is intended for software developers interested in developing
                applications using the OpenStack Quantum Layer-2 Networking Service
                    (<abbrev>API</abbrev>). </para>
        </abstract>
    </info>
    <chapter xml:id="Overview-d1e71">
        <title>Overview</title>
        <para>
            Quantum is a project to provide "network connectivity as a
            service" between devices managed by the OpenStack compute service.
            For more information on Quantum and the other network-related
            projects please check the Quantum home page
            (<link xlink:href="http://wiki.openstack.org/Quantum"/>)
            and the NetStack home page
            (<link xlink:href="http://wiki.openstack.org/Network"/>).
        </para>
        <para> We welcome feedback, comments, and bug reports at <link
            xlink:href="http://bugs.launchpad.net/Quantum">bugs.launchpad.net/Quantum</link>.
        </para>
        <section xml:id="Intended_Audience-d1e85">
            <title>Intended Audience</title>
            <para> This Guide is intended to assist software
            developers who want to develop applications using the
            Quantum API. To use the information provided
            here, you should first have a general understanding of the
            OpenStack Quantum network service, the OpenStack compute
            service (Nova), and the integration between the two.
            The user should also have access to a plugin providing the
            implementation for the API described in this document.
            Two plugins are included in the Quantum distribution:
			</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>Openvswitch - Implementing Quantum API with Open vSwitch</para>
                </listitem>
                <listitem>
                    <para>Cisco - Implementing Quantum API for Cisco UCS blades and
                    Nexus switches</para>
                </listitem>
            </itemizedlist>
            <para>
            You should also be familiar with:
			</para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>ReSTful web services</para>
                </listitem>
                <listitem>
                    <para>HTTP/1.1</para>
                </listitem>
                <listitem>
                    <para>JSON and/or XML data serialization formats</para>
                </listitem>
            </itemizedlist>
        </section>
        <section xml:id="Document_Change_History-d1e118">
            <title>Document Change History</title>
            <para>The most recent changes are described in the table below:</para>
            <informaltable rules='all'>
                    <thead>
                        <tr>
                            <td align="center" colspan="1">Revision Date</td>
                            <td align="center" colspan="4">Summary of Changes</td>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td colspan="1" align="center">September 22, 2011</td>
                            <td colspan="4">
                                 <itemizedlist spacing="compact">
                                     <listitem>
                                         <para>
                                             Initial release.
                                         </para>
                                    </listitem>
                                </itemizedlist>
                            </td>
                        </tr>
                    </tbody>
            </informaltable>
        </section>
        <?hard-pagebreak?>
        <section xml:id="Glossary">
        	<title>Glossary</title>
        	<informaltable rules='all'>
                    <thead>
                        <tr>
                            <td colspan="1" align="center">Term</td>
                            <td colspan="4" align="center">Description</td>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td colspan="1" align="center">
                            Entity
                            </td>
                            <td colspan="4">
                            A generic term for any piece of hardware or
                            software desiring to connect to the network
                            services provided by Quantum. An entity may
                            make use of Quantum by implementing a VIF.
                            </td>
                        </tr>
                        <tr>
                            <td colspan="1" align="center" bgcolor="#4F91BD">
                            Layer-2 network
                            </td>
                            <td colspan="4" bgcolor="#4F91BD">
                            A virtual Ethernet network managed by the Quantum
                            service. For the time being, Quantum will manage
                            only Ethernet networks.
                            </td>
                        </tr>
                        <tr>
                            <td align="center">
                            Network
                            </td>
                            <td colspan="4">
                            A virtual network providing connectivity
                            between entities, i.e.: collection of virtual
                            ports sharing network connectivity. In the
                            Quantum terminology, a network is always a Layer-2
                            network.
                            </td>
                        </tr>
                        <tr>
                            <td align="center" bgcolor="#4F91BD">
                            Plugin
                            </td>
                            <td colspan="4" bgcolor="#4F91BD">
                            Software component providing the actual
                            implementation for Quantum APIs.
                            </td>
                        </tr>
                        <tr>
                            <td align="center">
                            Port
                            </td>
                            <td colspan="4">
                            A port on the virtual network switch represented
                            by a Quantum virtual Layer-2 network.
                            </td>
                        </tr>
                        <tr>
                            <td align="center" bgcolor="#4F91BD">
                            VIF
                            </td>
                            <td colspan="4" bgcolor="#4F91BD">
                            A Virtual network InterFace plugged into a port of a Quantum
                            network; typically a virtual network interface
                            belonging to a VM
                            </td>
                        </tr>
                        <tr>
                            <td align="center">
                            Attachment
                            </td>
                            <td colspan="4">
                            Association of an interface identifier to a logical
                            port, which represent 'plugging' an interface into
                            a port.
                            </td>
                        </tr>
                    </tbody>
        	</informaltable>
        </section>
        <?hard-pagebreak?>
	    <section xml:id="Theory">
	    	<title>Theory of Operation</title>
	    	<para>
			This section presents the objects and semantics of Quantum’s
			logical model.
			</para><para>
			Quantum abstracts the physical implementation of the network,
			allowing plugins to configure and manage physical resources.
			Quantum is a standalone service, in that it requires no other
			project within OpenStack to function correctly.
			</para><para>
			Further Quantum is agnostic to the entities it allows to connect.
			While we anticipate Nova instances will be a heavy user of
			Quantum, any entity can make use of any Quantum created network
			so long as it provides an appropriate interfaces for exposing VIFs
			to Quantum itself.
			</para><para>
			Virtual Interfaces(VIF) in the logical model are analogous to
			physical network interface cards (NICs). VIFs are typically
			owned a managed by an external service; for instance when
			Quantum is used for building OpenStack networks,
			VIFs would be created, owned, and managed in Nova.
			VIFs are connected to Quantum networks via ports.
			A port is analogous to a port on a network switch, and it
			has an administrative state. Quantum API
			allows for controlling the administrative state of the port,
			which can be either 'DOWN' or 'ACTIVE'.
			</para><para>
			When a VIF is attached to a port the Quantum API creates
			an attachment object, which specifies the fact that a VIF with a
			given identifier is plugged into the port.
			</para><para>
			The Quantum plugin is responsible for managing virtual and/or
			physical network switches to implement the network forwarding
			connectivity described by the Quantum networks, ports, and
			attachments.
			</para><para>
			VIFs attached to ACTIVE ports are required to have access to the
			L2 broadcast domain defined by the network where they are attached.
			Each VIF shall be capable of exchanging traffic with all other
			entities attached through ACTIVE ports.
	    	</para>
	   </section>
	   <?hard-pagebreak?>
    </chapter>
    <chapter xml:id="Concepts-d1e369">
        <?dbhtml stop-chunking?>
        <title>Concepts</title>
        <para>
        To use the Quantum API effectively, developers should understand
        the concepts introduced in this chapter.
        </para>
        <section xml:id="Network">
            <title>Network</title>
            <para>
			Each tenant can define one or more networks. A network is a virtual
			isolated layer-2 broadcast domain reserved to the tenant.
			A tenant can create several ports for a network, and plug
			virtual interfaces into these ports.
			</para>
        </section>
        <section xml:id="Port">
            <title>Port</title>
            <para>
			A port represents a virtual switch port on a logical
			network switch where all the interfaces attached to a given
			network are connected.
			</para><para>
			A port has an administrative state which
			is either 'DOWN' or 'ACTIVE'. Ports which are administratively
			down will not be able to receive/send traffic.
			</para>
        </section>
        <section xml:id="Attachment">
            <title>Attachment</title>
            <para>
			An attachment represents an interface plugged into a logical
			port. At any time at most one attachment can be plugged into a
			given port.
			</para><para>
			An attachment typically identified a virtual network interface.
			Network interfaces are typically defined in an external services
			which uses Quantum, for instance the OpenStack Compute service,
			Nova.
            </para>
        </section>
    </chapter>
    <chapter xml:id="General_API_Information-d1e436">
        <title>General API Information</title>
        <para>
            The OpenStack Quantum API is defined as a ReSTful HTTP
            service. The API takes advantage of all aspects of the
            HTTP protocol (methods, URIs, media types, response codes,
            etc.) and providers are free to use existing features of
            the protocol such as caching, persistent connections, and
            content compression among others.  For example, providers
            who employ a caching layer may respond with a 203 when a
            request is served from the cache instead of a 200.
            Additionally, providers may offer support for conditional
            &GET; requests using ETags, or they may send a redirect in
            response to a &GET; request.  Clients should be written to
            account for these differences.
        </para>
        <section xml:id="Authentication-d1e444">
            <title>Authentication</title>
            <para>
                The current version of the OpenStack Quantum service
                does not require that each request will include the credentials
                of the user submitting the request.
            </para><para>
                However, Quantum deployments can support several
                authentication schemes (OAuth, Basic Auth, Token). The
                authentication scheme used is determined by the
                provider of the Quantum service. Please contact
                your provider to determine the best way to
                authenticate against this API.
            </para><para>
                Ideally, middleware modules for Authentication and/or Authorization
                should be inserted in the first stages of the Quantum pipeline
                (available in <code>etc/quantum.conf</code>).
            </para>
            <note>
                <para>
                    Some authentication schemes may require that the
                    API operate using SSL over HTTP (HTTPS).
                </para>
            </note>
        </section>
        <?hard-pagebreak?>
        <section xml:id="URI_structure">
        	<title>URI structure</title>
        	<para>
				Each request to the OpenStack Quantum API must refer to a
				specific version of the API itself, and it must also
				identify the tenant for which the request is being sent.
        	</para>
        	<para>
        		This information is specified in the URI. The URI
        		for each request to the OpenStack Quantum API should be
        		prefixed with the API version identifier and the tenant
        		identifier, as follows:
        	</para>
        	<para>
        		<code>/{Quantum-version}/tenants/{tenant-id}/{Quantum-API-entity}</code>
        	</para>
        	<para>
        		As an example, the following URI represents a request for
        		retrieving all the networks configured for the tenant "ABC"
        		using the 1.0 API.
        	</para>
        	<para>
        		<code>/v1.0/ABC/networks</code>
        	</para>
        </section>
        <section xml:id="Request_Response_Types">
            <title>Request/Response Types</title>
            <para>
                The OpenStack Quantum  API supports both the JSON and XML
                data serialization formats.
                The format for both the request and the response can be
                specified either using the <code>Content-Type</code> header,
				the <code>Accept</code> header or adding an <code>.xml</code>
				or <code>.json</code> extension to the request  URI.
            </para><para>
                If conflicting formats are specified in headers and/or format
                extensions, the latter takes precedence. XML is currently
                the default format for both requests and responses.
            </para>
            <table rules="all">
                <caption>JSON and XML Response Formats</caption>
                <thead>
                    <tr>
                        <td>Format</td>
                        <td>Accept Header</td>
                        <td>Query Extension</td>
                        <td>Default</td>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td>JSON</td>
                        <td>application/json</td>
                        <td>.json</td>
                        <td>No</td>
                    </tr>
                    <tr>
                        <td>XML</td>
                        <td>application/xml</td>
                        <td>.xml</td>
                        <td>Yes</td>
                    </tr>
                </tbody>
            </table>
            <example>
                <title>Request/Response with Headers: JSON</title>
                <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="javascript"><xi:include href="samples/networks-post-req.json" parse="text"/></programlisting>
                <literallayout class="monospaced">
HTTP/1.1 200 Accepted
Content-Type	application/json
Content-Length	59
                </literallayout>
                <programlisting language="javascript"><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>
                <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>
                <literallayout class="monospaced">
HTTP/1.1 200 Accepted
Content-Type	application/xml
Content-Length	52
                </literallayout>
                <programlisting language="javascript"><xi:include href="samples/networks-post-res.xml" parse="text"/></programlisting>
            </example>
            <?hard-pagebreak?>
            <example>
                <title>Request/Response with Extensions: JSON</title>
                <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="javascript"><xi:include href="samples/networks-post-req.json" parse="text"/></programlisting>
                <literallayout class="monospaced">
HTTP/1.1 200 Accepted
Content-Type	application/json
Content-Length	59
                </literallayout>
                <programlisting language="javascript"><xi:include href="samples/networks-post-res.json" parse="text"/></programlisting>
            </example>
        </section>
        <section xml:id="Async_behaviour">
        <title>Asynchronous Behavior by Quantum Plugins</title>
		<para>
		The Quantum API presents a logical model of network connectivity
		consisting of networks, ports, and attachments. It is up to
		the Quantum plugin to communicate with all managed virtual
		and/or physical switches to ensure that these devices implement
		packet forwarding behavior consistent with the logical model.
		</para><para>
		The plugin's task of mapping from the logical model to the physical
		world might happen asynchronously.  This means that when an API
		client modifies the logical model using an HTTP POST, PUT,
		or DELETE, the API call may return prior to the plugin performing
		any modifications to underlying virtual and/or physical switching
		devices.  The only guarantee an API client has is that all
		subsequent API calls will properly reflect the changed logical model.
		</para><para>
		As a concrete example, consider the case where a client uses an HTTP
		PUT to set the attachment for a port. There is no guarantee that
		packets sent by the interface named in the attachment will be
		forwarded immediately once the HTTP call returns.
		However, there is a guarantee that a subsequent HTTP GET to view
		the attachment on that port would return the new attachment value.
		</para>
		<note><para>
		Future versions of the API may expose a notion of an "operational status"
		on a logical entity like a network or port.
		</para><para>
		This would indicate whether the Quantum plugin had successfully
		configured virtual and/or physical switches in order to implement
		the network connectivity described by that element of the logical
		model.
		</para><para>
		For example, a port might have an operational status of <code>"DOWN"</code>
		because the VM interface specified as an attachment was not
		currently running on any physical server.
		</para></note>
        </section>
        <section xml:id="Versions">
            <title>Versions</title>
            <para>
                The Quantum API uses a URI based versioning scheme.
				The first element of the URI path contains the target
				version identifier.
            <example>
                <title>Request with URI versioning</title>
                <literallayout class="monospaced">
GET 			/v1.0/tenants/tenantX/networks HTTP/1.1
Host			127.0.0.1:9696
Accept			text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Content-Type	application/xml; charset=UTF-8
Content-Length	22
                </literallayout>
            </example>
             </para>
            <para>
                Available API versions can be retrieved
                by performing a &GET; on the root URL
                (i.e. with the version and everything to the
                right of it truncated) of the Quantum Service.
            </para>
            <example>
                <title>Versions List Request/Response (XML)</title>
                <literallayout class="monospaced">
GET 			/ HTTP/1.1
Host			127.0.0.1:9696
Content-Type	application/xml
                </literallayout>
                <programlisting language="xml"><xi:include href="samples/versions.xml" parse="text"/>
                </programlisting>
            </example>
            <?hard-pagebreak?>


            <example>
                <title>Version List Request/Response: JSON</title>
                <literallayout class="monospaced">
GET 			/ HTTP/1.1
Host			127.0.0.1:9696
Content-Type	application/json
                </literallayout>
                <programlisting language="javascript"><xi:include
                href="samples/versions.json" parse="text"/></programlisting>
            </example>
        </section>
        <?hard-pagebreak?>
        <section xml:id="Extensions">
            <title>Extensions</title>
            <para>
                The Quantum API is extensible. Extensions
                serve several purposes:
            </para>
            <itemizedlist spacing="compact">
                <listitem>
                    <para>
                    They allow the introduction of new
                	features in the API without requiring a
                	version change;
                    </para>
                </listitem>
                <listitem>
                    <para>
					They allow the introduction of vendor specific
                	niche functionality
                    </para>
                </listitem>
                <listitem>
                    <para>
					They act as a proving ground for experimental
					functionalities which might be included in a future
					version of the API.
                    </para>
                </listitem>
            </itemizedlist>
            <para>
				Applications can programmatically
                determine what extensions are available by performing
                a &GET; on the <code>/v1.0/extensions</code> URI.
                Note that this is a versioned request &mdash; that is,
                an extension available in one API version may not be
                available in another.
            </para>
            <example>
                <title>Extensions Response: XML</title>
                <programlisting language="xml"><?db-font-size 90%?>
<xi:include href="samples/extensions.xml" parse="text"/>
                </programlisting>
            </example>
            <?hard-pagebreak?>
            <example>
                <title>Extensions Response: JSON</title>
                <programlisting language="javascript"><?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>
            <para>
            <note>
				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.
            </note>
            </para>
            <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 (JSON)</title>
                    <programlisting language="javascript"><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">BadRequest</td>
                            <td bgcolor="#4F91BD">400</td>
                            <td bgcolor="#4F91BD" colspan="2">
                            Malformed request body.
                            The Quantum service is unable to parse the contents of the
                            request body.
                            </td>
                        </tr>
                        <tr>
                            <td>Unauthorized</td>
                            <td>401</td>
                            <td colspan="2">
                            User has not provided authentication credentials.
                            If authentication is provided by the Keystone identity
                            service, this might mean that either no authentication
                            token has been supplied in the request, or that the
                            token itself is either invalid or expired.
                            </td>
                        </tr>
                        <tr>
                            <td bgcolor="#4F91BD">Forbidden</td>
                            <td bgcolor="#4F91BD">403</td>
                            <td bgcolor="#4F91BD" colspan="2">
                            The user does not have the necessary rights
                            to execute the requested operation
                            </td>
                        </tr>
                        <tr>
                            <td>ItemNotFound</td>
                            <td>404</td>
                            <td colspan="2">
                            The requested resource does not exist on the Quantum API server
                            </td>
                        </tr>
                        <tr>
                            <td bgcolor="#4F91BD">NetworkNotFound</td>
                            <td bgcolor="#4F91BD">420</td>
                            <td bgcolor="#4F91BD" 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">PortNotFound</td>
                            <td bgcolor="#4F91BD">430</td>
                            <td bgcolor="#4F91BD" 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">PortInUse</td>
                            <td bgcolor="#4F91BD">432</td>
                            <td bgcolor="#4F91BD" colspan="2">
							The specified port cannot be removed as there is an attachment plugged in it.
                            </td>
                        </tr>
						<tr>
                            <td>AlreadyAttached</td>
                            <td>440</td>
                            <td colspan="2">
							Attachment is already plugged into another port.
                            </td>
                        </tr>
                    </tbody>
                </table>
                <note>
                <para>
                The error codes 401 and 403 will be returned only if some
                Authentication/Authorization system has been enabled in the
                Quantum pipeline
                </para>
                </note>
        </section>
    </chapter>
    <chapter xml:id="API_Operations">
        <title>API Operations</title>
        <section xml:id="Networks">
            <title>Networks</title>
            <para>
            This section describes the operations exposed by Quantum API for
            manipulating network resources.
            </para>
            <section xml:id="List_Networks">
                <title>List Networks</title>
                <informaltable rules="all">
                    <thead>
                        <tr>
                            <td colspan="1">Verb</td>
                            <td colspan="2">URI</td>
                            <td colspan="3">Description</td>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td colspan="1">&GET;</td>
                            <td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks</td>
                            <td colspan="3">
                            List summary of networks configured in Quantum for
                            a given tenant, identified by tenant-id
                            </td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>200</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>)
                </simpara>
                <para>
                    This operation returns the list of all networks
                    currently defined in Quantum for the tenant
                    specified in the request URI.
                    The returned list will provide the unique identifier
                    of each network configured for the tenant specified
                    in the resource URI.
                </para>
                <note>
                    <para>
                        <property>TenantId</property> is a unique tenant
                        identifier. The Quantum service does not directly
                        manages tenants. Tenant management should be
                        performed by the identity service
                    </para>
                </note>
                <para>This operation does not require a request body.</para>
                <example>
                    <title>Networks List Request/Response (XML)</title>
                    <para>Request:</para>
                <literallayout class="monospaced">
GET /tenants/XYZ/networks.xml
                </literallayout>
                    <para>Response:</para>
                    <programlisting language="xml"><xi:include href="samples/networks-get-res.xml" parse="text"/>
                    </programlisting>
                </example>
            	<?hard-pagebreak?>
                <example>
                    <title>Networks List Request/Response (JSON)</title>
                    <para>Request:</para>
	                <literallayout class="monospaced">
GET /tenants/XYZ/networks.json
	                </literallayout>
                    <para>Response:</para>
                    <programlisting language="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/detail</td>
                            <td colspan="3">
                            List more detailed information about networks
                            configured in Quantum for a given tenant,
                            identified by tenant-id
                            </td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>200</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>)
                </simpara>
                <para>
                This operation returns the list of all networks currently
                defined in Quantum; for each network, its identifier
                and name are returned.
                </para>
                <para>This operation does not require a request body.</para>
                <example>
                    <title>Networks List 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 Request/Response (JSON)</title>
                    <para>Request:</para>
	                <literallayout class="monospaced">
GET /tenants/XYZ/networks/detail.json
	                </literallayout>
                    <para>Response:</para>
                    <programlisting language="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis></td>
                            <td colspan="3">
							List information for a specific network,
							identified by <emphasis>network-id</emphasis>,
							for a given tenant, identified by <emphasis>tenant-id</emphasis>.
                            </td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>200</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>),
                    NetworkNotFound (<errorcode>420</errorcode>),
                </simpara>
                <para>
				This operation returns the identifier and the name for a
				specific network configured in Quantum.
				</para><para>
				This operation does not require a request body.</para>
                <example>
                    <title>Show Network Request/Response (XML)</title>
                    <para>Request:</para>
                <literallayout class="monospaced">
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.xml
                </literallayout>
                    <para>Response:</para>
                    <programlisting language="xml"><xi:include href="samples/network-get-res.xml" parse="text"/>
                    </programlisting>
                </example>
                <?hard-pagebreak?>
                <example>
                    <title>Show Network Request/Response (JSON)</title>
                    <para>Request:</para>
	                <literallayout class="monospaced">
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.json
	                </literallayout>
                    <para>Response:</para>
                    <programlisting language="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis>/detail</td>
                            <td colspan="3">
							List detailed information for a specific network,
							identified by <emphasis>network-id</emphasis>,
							for a given tenant, identified by <emphasis>tenant-id</emphasis>.
                            </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 Detail 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 Detail 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="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks</td>
                            <td colspan="3">
							Creates a new logical layer-2 network for the
							tenant identified by <emphasis>tenant-id</emphasis>
							</td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>200</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    BadRequest (<errorcode>400</errorcode>)
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>),
                </simpara>
                <para>
				This operation creates a Layer-2 network in
				Quantum based on the information provided in the request body.
				</para><para>
				Quantum validates the request, and dispatches it to the plugin,
				and then returns the unique identifier of the network to the
				caller. Although the network API entity can be immediately used
				for other operations, this does not guarantee that the network
				will be available when the API call returns, as this depends
				on the particular plugin implementation.
				</para><para>
				If the validation phase fails, the network object is not
				created at all, and a 400 error is returned to the caller.
				</para>
				<note>
					<para>
					The Quantum API v1.0 does not provide an interface
					for checking the progress of asynchronous operations
					performed by plugins.
					</para>
					<para>
					This will be addressed in future releases of the
					Quantum API.
					</para>
				</note>
                <para>
				The body for this request must contain a Network object
				specifying a symbolic name for the network.
                </para>
                <example>
                    <title>Create Network Request/Response (XML)</title>
                    <para>Request:</para>
                <literallayout class="monospaced">
POST /tenants/XYZ/networks.xml
                </literallayout>
                    <programlisting language="xml"><xi:include href="samples/network-post-req.xml" parse="text"/>
                    </programlisting>
                    <para>Response:</para>
                    <programlisting language="xml"><xi:include href="samples/network-post-res.xml" parse="text"/>
                    </programlisting>
                </example>
                <example>
                    <title>Create Network Request/Response (JSON)</title>
                    <para>Request:</para>
	                <literallayout class="monospaced">
POST /tenants/XYZ/networks.json
	                </literallayout>
                    <programlisting language="javascript"><xi:include href="samples/network-post-req.json" parse="text"/>
                    </programlisting>
                    <para>Response:</para>
                    <programlisting language="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis></td>
                            <td colspan="3">
                            Renames the network identified by
                            <emphasis>network-id</emphasis> for the
							tenant identified by <emphasis>tenant-id</emphasis>
							</td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>204</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    BadRequest (<errorcode>400</errorcode>)
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>),
                    NetworkNotFound (<errorcode>420</errorcode>)
                </simpara>
                <para>
				This operation renames a Quantum network using the data
				provided in the request body.
				</para>
                <para>
				The body for this request must contain a Network object
				specifying a symbolic name for the network. The network
				entity specified in the request body can contain the
				network's identifier as well, even if it is not required,
				as the identifier must be expressed on the URI; in this
				case the identifier in the request body will be ignored.
                </para>
                <example>
                    <title>Update Network Request/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 returned in response body</emphasis></para>
                </example>
                <example>
                    <title>Update Network Request/Response (JSON)</title>
                    <para>Request:</para>
	                <literallayout class="monospaced">
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json
	                </literallayout>
                    <programlisting language="javascript"><xi:include href="samples/network-post-req.json" parse="text"/>
                    </programlisting>
                    <para>Response:</para>
                    <para><emphasis>No data returned in 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/<emphasis>{tenant-id}</emphasis>/networks/<emphasis>{network-id}</emphasis></td>
                            <td colspan="3">
                            Destroys the network identified by
                            <emphasis>network-id</emphasis> for the
							tenant identified by <emphasis>tenant-id</emphasis>
							</td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>204</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    BadRequest (<errorcode>400</errorcode>)
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>),
                    NetworkNotFound (<errorcode>420</errorcode>),
                    NetworkInUse (<errorcode>421</errorcode>)
                </simpara>
                <para>
				This operation removes the network specified in the URI.
				This request will fail as long as there is at least one
				port on the network with attachments plugged in it.
				If all ports on the networks are unattached, they will
				be destroyed together with the network itself.
				</para>
				<para>
				As for the create operation there is no guarantee that the
				plugin will have completely removed the network when the
				call returns. Quantum forwards the request to the plugin,
				which will then destroy the network.
				</para><para>
				Please note that this operation cannot be undone.
				</para>
                <para>
                This operation does not require a request 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 returned in response body</emphasis></para>
                </example>
                <example>
                    <title>Update Network Request/Response (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 returned in response body</emphasis></para>
                    </example>
            </section>
        </section>
        <section xml:id="Ports">
            <title>Ports</title>
            <para>
            This section describes the operations exposed by Quantum API for
            manipulating port resources.
            </para>
			<section xml:id="List_Ports">
                <title>List Ports</title>
                <informaltable rules="all">
                    <thead>
                        <tr>
                            <td colspan="1">Verb</td>
                            <td colspan="2">URI</td>
                            <td colspan="3">Description</td>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td colspan="1">&GET;</td>
                            <td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}/ports</emphasis></td>
                            <td colspan="3">
							Lists all the ports currently defined for a Quantum network,
							identified by <emphasis>network-id</emphasis>
							</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="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/detail</td>
                            <td colspan="3">
							Lists detailed information for all the ports currently defined
							for the network identified by <emphasis>network-id</emphasis>
							</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="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/
                            				<emphasis>{port-id}</emphasis></td>
                            <td colspan="3">
							Retrieves the port
							<emphasis>port-id</emphasis> configured for the
							network <emphasis>network-id</emphasis> belonging
							to the tenant <emphasis>tenant-id</emphasis>.
							</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="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/
                            				<emphasis>{port-id}</emphasis>/detail</td>
                            <td colspan="3">
							Retrieves detailed information for the port
							<emphasis>port-id</emphasis> configured for the
							network <emphasis>network-id</emphasis> belonging
							to the tenant <emphasis>tenant-id</emphasis>.
							</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 Detail 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 Detail 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="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports</td>
                            <td colspan="3">
							Creates a port on the network specified
							in the request URI, identified by
							<emphasis>network-id</emphasis>
							</td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>200</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    BadRequest (<errorcode>400</errorcode>),
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>),
                    NetworkNotFound (<errorcode>420</errorcode>),
                    RequestedStateInvalid (<errorcode>431</errorcode>)
                </simpara>
                <para>
				This operation creates a port on a Quantum network based on
				the information provided in the request body.
				Quantum validates the request, and dispatches the request
				to the plugin, which creates the port and attaches
				it to the appropriate network.
				</para><para>
				This operation could not be implemented for some
				plugins as the number of ports available might be fixed
				when the network is created.
				</para><para>
				If the validation phase fails, the port object is not
				created at all, and a <code>BadRequest</code> error is returned
				to the caller.
				</para><para>
				The operation returns a port with an identifier, and set its
				administrative state set to <code>DOWN</code>, unless a state
				has been explicitly specified in the request body.
				</para><para>
				Please note that 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><para>
				The request body is not mandatory 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="xml"><xi:include href="samples/port-post-req.json" parse="text"/>
                	</programlisting>
                    <para>Response:</para>
                    <programlisting language="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/
                            				<emphasis>{port-id}</emphasis></td>
                            <td colspan="3">
							Sets the administrative state for the port
							identified by <emphasis>port-id</emphasis>
							on the network identified by
							<emphasis>network-id</emphasis>
							</td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>204</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    BadRequest (<errorcode>400</errorcode>),
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>),
                    NetworkNotFound (<errorcode>420</errorcode>),
                    PortNotFound (<errorcode>430</errorcode>),
                    RequestedStateInvalid (<errorcode>431</errorcode>)
                </simpara>
                <para>
				This operation sets the administrative state for a port.
				Currently Quantum recognizes two port states:
				<code>DOWN</code> and <code>ACTIVE</code>. In the
				<code>DOWN</code> state a port will not provide
				connectivity to the network.
				</para><para>
				This feature allows the tenant the ability to take entities
				offline without affecting the logical topology.
				</para><para>
				The operation will return the <code>RequestedStateInvalid</code>
				error code if the specified administrative state is not either
				<code>DOWN</code> or <code>ACTIVE</code>.
				</para><para>
				The operation's request body must contain a Port object with
				the new administrative state for the port.
				</para>
                <example>
                    <title>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 returned in response body.</emphasis></para>
                </example>
                <example>
                    <title>Set Port State Request/Response (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="xml"><xi:include href="samples/port-post-req.json" parse="text"/>
                	</programlisting>
                    <para>Response:</para>
                    <para><emphasis>No data returned in 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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/
                            				<emphasis>{port-id}</emphasis></td>
                            <td colspan="3">
							Destroys the port
							identified by <emphasis>port-id</emphasis>
							on the network identified by
							<emphasis>network-id</emphasis>
							</td>
                        </tr>
                    </tbody>
                </informaltable>
                <simpara>
                    Normal Response Code(s):
                    <returnvalue>204</returnvalue>
                </simpara>
                <simpara>
                    Error Response Code(s):
                    BadRequest (<errorcode>400</errorcode>),
                    Unauthorized (<errorcode>401</errorcode>),
                    Forbidden (<errorcode>403</errorcode>),
                    NetworkNotFound (<errorcode>420</errorcode>),
                    PortNotFound (<errorcode>430</errorcode>),
                    PortInUse (<errorcode>432</errorcode>)
                </simpara>
                <para>
				This operation removes a port from a Quantum network.
				This operation might not be available for plugins in
				which the number of ports is fixed at network creation;
				in this case ports should not be deleted, just as they
				cannot be created.
				</para><para>
				The operation is not recoverable and will fail if an
				attachment is plugged into the port. 			#
				</para><para>
				This operation does not require a request body.
				</para>
                <example>
                    <title>Delete Port 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 returned in response body.</emphasis></para>
                </example>
                <example>
                    <title>Delete Port State Request/Response (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 returned in response body.</emphasis></para>
                </example>
            </section>
        </section>
        <section xml:id="Attachments">
            <title>Attachments</title>
            <para>
            This section describes the operations exposed by Quantum API for
            manipulating port attachments.
            </para><para>
			An attachment is typically a virtual network interface
			belonging to a VM instance. Different kinds of resources
			can be defined in the future.
            </para>
			<section xml:id="Show_Attachment">
                <title>Show Attachment for Port</title>
                <informaltable rules="all">
                    <thead>
                        <tr>
                            <td colspan="1">Verb</td>
                            <td colspan="2">URI</td>
                            <td colspan="3">Description</td>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td colspan="1">&GET;</td>
                            <td colspan="2">/tenants/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/
                            				<emphasis>{port-id}</emphasis>/attachment</td>
                            <td colspan="3">
							Returns the identifier of the attachment plugged
							into the specified port, identified by
							<emphasis>port-id</emphasis>.
							</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 (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 (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="javascript"><xi:include href="samples/att-get-res.json" parse="text"/>
                    </programlisting>
                    <para>Response (attachment not set):</para>
                    <programlisting language="javascript"><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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/
                            				<emphasis>{port-id}</emphasis>/attachment</td>
                            <td colspan="3">
							Plugs a resource, i.e. a virtual network interface
							into the port identified by
							<emphasis>port-id</emphasis>.
							</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>
				The request will be first validated by Quantum and then
				dispatched 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 somewhere else;
	                    </para>
	                </listitem>
	                <listitem>
	                    <para>
						There is already another attachment plugged
						into the specified port.
	                    </para>
	                </listitem>
	            </itemizedlist>
				<para>
				If the validation phase 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 (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>No data returned in response body</para>
                </example>
                <example>
                    <title>Plug Attachment (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>No data returned in response body</para>
				</example>
            </section>
			<section xml:id="Delete_Attachment">
                <title>Unplug 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/<emphasis>{tenant-id}</emphasis>/networks/
                            				<emphasis>{network-id}</emphasis>/ports/
                            				<emphasis>{port-id}</emphasis>/attachment</td>
                            <td colspan="3">
							Removes the attachment currently plugged
							into the port identified by
							<emphasis>port-id</emphasis>.
							</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 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>Remove Attachment (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>No data returned in response body</para>
                </example>
                <example>
                    <title>Remove Attachment (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>No data returned in response body</para>
				</example>
            </section>
        </section>
    </chapter>
</book>