Jump to: navigation, search

Difference between revisions of "QuantumAPISpec"

(Updating glossary, theory of operation, and concepts)
m (Text replace - "__NOTOC__" to "")
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
__NOTOC__
 
= Quantum API Specification =
 
<<[[TableOfContents]]()>>
 
  
== Introduction ==
+
Please see: http://docs.openstack.org/api/openstack-network/2.0/content/index.html
<span style="font-size: larger"><span style="font-size: smaller">Quantum is a project to provide "network connectivity as a service" between devices managed by other Openstack services such as nova.  For more information on Quantum and the other network-related projects please check the [[Quantum|Quantum home page]] and the [[Network|Network projects home page]]. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">As Quantum provides “network connectivity as a service”, this API specification defines Layer-2 operations only. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This document contains the specification for the version 1.0 of the core API for the Quantum service. <<BR>>For each operation this document specifies:</span></span>
 
 
 
* Request method (e.g.: GET, PUT, POST, DELETE)
 
* Request relative URI
 
* Request format
 
* Response format
 
 
 
Quantum core API allows for both JSON and XML format to be used.
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This specification document is structured as follows:</span></span>
 
 
 
* Glossary: introduces the terminology used throughout the document;
 
* Theory of operation: discusses how the Quantum service works in principle;
 
* Concepts: describes the resources managed by the Quantum API;
 
* Operation List: detailed described of the operation exposed by the Quantum API.<span style="font-size: larger"> </span>
 
 
 
== Glossary ==
 
{| border="1" cellpadding="2" cellspacing="0"
 
|<#4F91BD>|Entity
 
|-
 
| Network
 
|-
 
|<#4F91BD>|Plugin
 
|-
 
| Logical Port
 
|-
 
|<#4F91BD>|VIF
 
|-
 
| Attachment
 
|}
 
 
 
== Theory of Operation ==
 
This section presents the objects and semantics of Quantum’s logical model.
 
 
 
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 projects within Openstack to function correctly. Further Quantum is agnostic to the entities it allows to connect.
 
 
 
While we anticipate Nova created 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.
 
 
 
Virtual Interfaces(VIF) in the logical model are analogous to physical network interface cards (NIC). VIFs are typycally 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 logical ports. A logical port is analogous to a port on a network switch, and it has an administrative state and an operational state. Quantum API allows for controlling the administrative state of the port, which can be either 'DOWN' or 'ACTIVE'.
 
 
 
When a VIF is attached to a logical port the Quantum API creates an attachment object, which specifies the fact that a VIF with a given identifier is plugged into the logical port. The plugin is responsible for creating the attachment object, as well as performing all required operations on physical and virtual appliances.
 
 
 
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.
 
 
 
== Concepts ==
 
=== Network ===
 
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 logical ports for a network, and plug virtual interfaces into these ports.
 
 
 
=== Port ===
 
A logical port represents a virtual switch port on an ideal network switch where all the interfaces attached to a given network are connected.
 
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.
 
 
 
=== Attachment ===
 
An attachment resources represents the act of plugging an interface into a logical port. Each logical port has one optional attachment; the attachment is required to express the identifier of the network interface plugged in it. Netowrk interfaces are tipycally defined outside of Quantum.
 
 
 
== Operation List ==
 
List of error response codes:
 
{| border="1" cellpadding="2" cellspacing="0"
 
|< >|'''Code'''
 
| '''Name'''
 
|-
 
|<#4F91BD><<Anchor(400-[[BadRequest]])>|>400
 
|<#4F91BD>|Bad Request
 
|-
 
|<<Anchor(401-Unauthorized)>|>401
 
| Unauthorized
 
|-
 
|<#4F91BD><<Anchor(420-[[NetworkNotFound]])>|>420
 
|<#4F91BD>|NetworkNotFound
 
|-
 
|<<Anchor(421-[[NetworkInUse]])>|>421
 
| NetworkInUse
 
|-
 
|<#4F91BD><<Anchor(422-[[NetworkNameExists]])>|>422
 
|<#4F91BD>|NetworkNameExists
 
|-
 
|-
 
|<#4F91BD><<Anchor(430-[[PortNotFound]])>|>430
 
|<#4F91BD>|PortNotFound
 
|-
 
|<<Anchor(431-[[RequestedStateInvalid]])>|>431
 
| RequestedStateInvalid
 
|-
 
|<#4F91BD><<Anchor(432-[[PortInUse]])>|>432
 
|<#4F91BD>|PortInUse
 
|-
 
|<<Anchor(433-[[PortIsDown]])>|>433
 
| PortIsDown
 
|-
 
|<#4F91BD><<Anchor(440-[[AlreadyAttached]])>|>440
 
|<#4F91BD>|AlreadyAttached
 
|-
 
|<<Anchor(441-[[AttachmentNotReady]])>|>441
 
| AttachmentNotReady
 
|}
 
 
 
Some operations accept input parameters into the request body. See the complete operation list for information concerning the format of the request body.
 
 
 
Quantum API is able to parse request and generate responses both in JSON and XML. The format is chosen according to the following criteria:
 
 
 
# Suffix on request URI<<BR>>''.json for JSON format, .xml for XML format''
 
# ''Content-Type request header''<<BR>>''"application/json" for JSON format, "application/xml" for XML format''
 
# Accept-* request headers<<BR>>''"application/json" for JSON format, "application/xml" for XML format''
 
 
 
<span style="font-size: larger"><span id="op1"></span><<Anchor([[GetNetworks]])>>  </span>
 
 
 
----
 
=== List networks ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation returns the list of all networks currently defined in Quantum; returned list includes at least the network’s unique identifier. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<networks>
 
    <network id="8bec1293-16bd-4568-ba75-1f58bec0b4c3"/>
 
    <network id="2a39409c-7146-4501-8429-3579e03e9b56"/>
 
</networks>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
    "networks":
 
        [
 
          {"id": "8bec1293-16bd-4568-ba75-1f58bec0b4c3"},
 
          {"id": "2a39409c-7146-4501-8429-3579e03e9b56"}
 
        ]
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]], [[#A401-Unauthorized|#401-Unauthorized]] </span> </span>
 
 
 
<span style="font-size: larger"><span id="op1d"></span><<Anchor([[GetNetworksDetail]])>>  </span>
 
 
 
----
 
=== List networks (detail) ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/detail
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation returns the list of all networks currently defined in Quantum; for each network, its identifier and name are returned. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/detail.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<networks>
 
    <network id="8bec1293-16bd-4568-ba75-1f58bec0b4c3"
 
            name="network_1"/>
 
    <network id="2a39409c-7146-4501-8429-3579e03e9b56"
 
            name="network_2/>
 
"/>
 
</networks>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/detail.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
    "networks":
 
        [
 
          {
 
          "id": "8bec1293-16bd-4568-ba75-1f58bec0b4c3",
 
          "name": "network_1"
 
          },
 
          {
 
          "id": "2a39409c-7146-4501-8429-3579e03e9b56",
 
          "name": "network_2"
 
          }
 
        ]
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]], [[#A401-Unauthorized|#401-Unauthorized]] </span> </span>
 
 
 
<span style="font-size: larger"><span id="op2"></span><<Anchor([[ShowNetwork]])>>  </span>
 
 
 
----
 
=== Show network ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/{network-id}
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation return the identifier and the name for a specific network configured in Quantum.' </span></span> Details about ports configured for the network and resources attached to can be retrieved using the ''detail'' action for this operation: <code><nowiki> GET /tenants/{tenant-id}/networks/{network-id}/detail </nowiki></code>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
    <network
 
          id="8bec1293-16bd-4568-ba75-1f58bec0b4c3"
 
          name="test_network"/>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
  "network":
 
      {
 
          "id": "8bec1293-16bd-4568-ba75-1f58bec0b4c3",
 
          "name": "test_network"
 
      }
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200 </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]], [[#A401-Unauthorized|#401-Unauthorized]], [[#A420-NetworkNotFound|#420-NetworkNotFound]] </span></span> <span style="font-size: larger"><span id="op2d"></span><<Anchor([[ShowNetworkDetail]])>>  </span>
 
 
 
----
 
=== Show network (details) ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/{network-id}/detail
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">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. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3/detail.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
    <network
 
          id="8bec1293-16bd-4568-ba75-1f58bec0b4c3"
 
          name="test_network">
 
        <ports>
 
            <port id="98017ddc-efc8-4c25-a915-774b2a633855" status="DOWN"/>
 
            <port id="b832be00-6553-4f69-af33-acd554e36d08" status="ACTIVE">
 
                <attachment id="test_interface_identifier" status="READY"/>
 
            </port>
 
        </ports>
 
    </network>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3/detail.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
  "network":
 
      {
 
          "id": "8bec1293-16bd-4568-ba75-1f58bec0b4c3",
 
          "name": "test_network"
 
          "ports":
 
              [
 
                {
 
                    "id": "98017ddc-efc8-4c25-a915-774b2a633855",
 
                    "state": "DOWN"
 
                },
 
                {
 
                    "id": b832be00-6553-4f69-af33-acd554e36d08",
 
                    "state": "ACTIVE",
 
                    "attachment":
 
                        {
 
                            "id": "test_interface_identifier"
 
                        }
 
                }
 
              ]
 
      }
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200 </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]], [[#A401-Unauthorized|#401-Unauthorized]], [[#A420-NetworkNotFound|#420-NetworkNotFound]] </span></span> <span style="font-size: larger"><span id="op3"></span><<Anchor([[PostNetwork]])>>  </span>
 
 
 
----
 
=== Create Network ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| POST
 
| /tenants/{tenant-id}/networks
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The body for this request should contain a Network object includind a symbolic name for the network.  Note that network names must be unique for each tenant. The unique identifier for the Network will be returned with the response.</span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation asynchronously creates a Layer-2 network in Quantum based on the information provided in the request body.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Quantum validates the request, and dispatches it to the plugin, and then returns the unique identifier of the network to the caller, who can check the progress of the operation performing a GET on networks/id.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Resources for the new network can be either provided at create time or when virtual interfaces are plugged into this network depending on the particular plugin implementation.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">If the validation phase fails, the network object is not created at all, and a 400 error is returned to the caller. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
POST /tenants/XYZ/networks.xml
 
 
 
<network name="test_create_network"/>
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<network id="158233b0-ca9a-40b4-8614-54a4a99d47d1"/>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
POST tenants/XYZ/networks.json
 
 
 
{
 
  "network":
 
      {
 
            "name": "test_create_network"
 
      }
 
}
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
  "network":
 
      {
 
          "id": "158233b0-ca9a-40b4-8614-54a4a99d47d1",
 
      }
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 202  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A400-BadRequest|#400-BadRequest]],[[#A422-NetworkAlreadyExists|#422-NetworkAlreadyExists]],  </span></span>
 
 
 
<span style="font-size: larger"><span id="op4"></span><<Anchor([[PutNetwork]])>>  </span>
 
 
 
----
 
=== Update Network ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| PUT
 
| /tenants/{tenant-id}/networks/{network-id}
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The request body for this operation must contain the new symbolic name for the network.  Note that network names must be unique for each tenant. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' This operation asynchronously updates a network in Quantum according to the information provided in the request body.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml
 
 
 
<network name="new_network_name"/>
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json
 
 
 
{
 
  "network":
 
      {
 
            "name": "new_network_name"
 
      }
 
}
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 204 </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A400-BadRequest|#400-BadRequest]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],[[#A422-NetworkNameExists|#422-NetworkNameExists]], </span></span><span style="font-size: larger"><span id="op5"></span><<Anchor([[DeleteNetwork]])>>  </span>
 
 
 
----
 
 
 
=== Delete Network ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| DELETE
 
| /tenants/{tenant-id}/networks/{network-id}
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation removes the network specified in the URI. This request will fail as long as there is at least one "active" port on the network. Logical ports will be destroyed together with the network.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The operation is asynchronous. Quantum forwards the request to the plugin, which will then destroy the network. Callers can check the current status of the operation by performing a GET on networks/id. The operation has complete when a [[#A420-NetworkNotFound|#420-NetworkNotFound]] is returned.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation is not recoverable. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 204  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-Service_Unavailable|#470-Service Unavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],[[#A421-NetworkInUse|#421-NetworkInUse]],</span></span><span style="font-size: larger"><span id="op6"></span><<Anchor([[GetPorts]])>>  </span>
 
 
 
----
 
=== List logical ports for network ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/{network-id}/ports
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation lists all the ports currently configured for a network. Response for each port includes at least its unique identifier. If no logical ports have been created on the network an empty list will be returned. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<ports>
 
    <port id="98017ddc-efc8-4c25-a915-774b2a633855"/>
 
    <port id="b832be00-6553-4f69-af33-acd554e36d08"/>
 
</ports>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
    "ports":
 
        [
 
          {"id": "98017ddc-efc8-4c25-a915-774b2a633855"},
 
          {"id": "b832be00-6553-4f69-af33-acd554e36d08"}
 
        ]
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]]</span></span>
 
 
 
<span style="font-size: larger"><span id="op6d"></span><<Anchor([[GetPortsDetail]])>>  </span>
 
 
 
----
 
=== List logical ports (detail) ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/{network-id}/ports/detail
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">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  logical ports have been created on the network an empty list will be  returned. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/detail.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<ports>
 
    <port id="98017ddc-efc8-4c25-a915-774b2a633855"
 
          state="ACTIVE"/>
 
    <port id="b832be00-6553-4f69-af33-acd554e36d08"
 
          state="ACTIVE"/>
 
</ports>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/detail.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
    "ports":
 
        [
 
          {"id": "98017ddc-efc8-4c25-a915-774b2a633855"},
 
          {"id": "b832be00-6553-4f69-af33-acd554e36d08"}
 
        ]
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]]</span></span>
 
 
 
<span style="font-size: larger"><span id="op7"></span><<Anchor([[ShowPort]])>>  </span>
 
 
 
----
 
=== Show port ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/{network-id}/ports/{port-id}
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation provides the identifier and the current state for specific port configured for a given network. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<port
 
    id="98017ddc-efc8-4c25-a915-774b2a633855"
 
    state="DOWN"/>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
    "port":
 
        {
 
            "state": "DOWN",
 
            "id": "98017ddc-efc8-4c25-a915-774b2a633855"
 
        }
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],</span></span>[[#A423-NetworkNotReady|#423-NetworkNotReady,]]<span style="font-size: larger"><span style="font-size: smaller">[[#A430-PortNotFound|#430-PortNotFound]]  </span> </span>
 
 
 
<span style="font-size: larger"><span id="op7d"></span><<Anchor([[ShowPortDetails]])>>  </span>
 
 
 
----
 
=== Show port (Detail) ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/{network-id}/ports/{port-id}/detail
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation provides at least the identifier and the current state for specific port configured for a given network. </span></span> If an attachment is plugged into the port, this operation will return the identifier of the attachment as well.
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855/detail.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<port
 
    id="98017ddc-efc8-4c25-a915-774b2a633855"
 
    state="DOWN">
 
    <attachment id="test_interface_id"/>
 
</port>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855/detail.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
    "port":
 
        {
 
            "state": "DOWN",
 
            "id": "98017ddc-efc8-4c25-a915-774b2a633855"
 
            "attachment":
 
                {
 
                    "id": "test_interface_id"
 
                }
 
        }
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],</span></span>[[#A423-NetworkNotReady|#423-NetworkNotReady,]]<span style="font-size: larger"><span style="font-size: smaller">[[#A430-PortNotFound|#430-PortNotFound]]  </span></span><span style="font-size: larger"><span id="op8"></span><<Anchor([[PostPort]])>>  </span>
 
 
 
----
 
=== Create Port ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| POST
 
| /tenants/{tenant-id}/networks/{network-id}/ports
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The request body is not mandatory, but can optionally contain the state of the newly created port, which can be either 'DOWN' or 'ACTIVE'. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation asynchronously 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 logical port and attaches it to the appropriate network. Resources for the new port can be either provided at create time or when virtual interfaces are plugged into this port depending on the particular plugin implementation.  Also, this operation could not be implemented for some plugins as the number of ports available might be fixed when the network is created.  If the validation phase fails, the port object is not created at all, and a [[#A400-BadRequest|#400-BadRequest]] error is returned to the caller.  The operation returns a port with an identifier, and state set to DOWN. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
POST /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.xml
 
 
 
<port state="ACTIVE"/>
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<port id="98017ddc-efc8-4c25-a915-774b2a633855"/>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
POST /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.json
 
 
 
{
 
"port":
 
    { "state": "ACTIVE" }
 
}
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
    "port":
 
        {
 
            "id": "98017ddc-efc8-4c25-a915-774b2a633855"
 
        }
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 202  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A400-BadRequest|#400-BadRequest]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],</span></span><span style="font-size: larger"><span style="font-size: smaller">[[#A431-RequestedStateInvalid|#431-RequestedStateInvalid]] </span>  </span>
 
 
 
<span style="font-size: larger"><span id="op9"></span><<Anchor([[DeletePort]])>>  </span>
 
 
 
----
 
=== Delete Port ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| DELETE
 
| /tenants/{tenant-id}/networks/{network-id}/ports/{port-id}
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation removes a logical 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.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The operation is not recoverable and will fail if an attachment is plugged into the port. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 204 </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],</span></span><span style="font-size: larger"><span style="font-size: smaller">[[#A430-PortNotFound|#430-PortNotFound]],[[#A432-PortInUse|#432-PortInUse]]  </span></span>
 
 
 
<span style="font-size: larger"><span id="op10"></span><<Anchor([[GetPortAttachment]])>>  </span>
 
 
 
----
 
=== Set Port State ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| PUT
 
| /tenants/{tenant-id}/networks/{network-id}/ports/{port-id}
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' The operation's request body contains the new administrative state for the logical port. Valid values are 'DOWN' and 'ACTIVE' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation attempts to set the state of the logical port.  Currently Quantum recognizes two port states: DOWN and ACTIVE. In the DOWN state a port is not required to be bound to physical resources of the network.  Setting a currently active port to down allows plugins to make intelligent use of current resources.  Additionally it allows the tenant the ability to take entities offline without destroying their logical topology.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The operation will return [[#A431-RequestedStateInvalid|#431-RequestedStateInvalid]] if the specified administrative state is not DOWN or ACTIVE. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml
 
 
 
<port state="ACTIVE"/>
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json
 
 
 
{
 
"port":
 
    { "state": "ACTIVE" }
 
}
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 204 </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A400-BadRequest|#400-BadRequest]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],</span></span><span style="font-size: larger"><span style="font-size: smaller">[[#A430-PortNotFound|#430-PortNotFound]],[[#A433-PortNotReady|#431-RequestedStateInvalid]]  </span></span>
 
 
 
<span style="font-size: larger"><span id="op10"></span><<Anchor([[GetPortAttachment]])>>  </span>
 
 
 
----
 
=== Retrieve attachment for port ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| GET
 
| /tenants/{tenant-id}/networks/{network-id}/ports/{port-id}/attachment
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation returns configuration details for the attachment plugged into the port specified in the request URI.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This information is a reference to a virtual interface identifier, which could be either: </span></span>
 
 
 
* <span style="font-size: larger"><span style="font-size: smaller">A reference to a resource managed by Quantum; </span></span>
 
* <span style="font-size: larger"><span style="font-size: smaller">A reference to an external resource not managed by Quantum (for instance a network interface defined in nova); </span></span>
 
 
 
If no attachment is currently plugged into the logical port, the operation does not return any attachment identifier in the response. The response will contain an empty 'attachment' element.
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
<attachment id="test_interface_identifier"/>
 
</nowiki></pre>
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
 
 
<pre><nowiki>
 
{
 
"attachment":
 
    {
 
        "id": "test_interface_identifier"
 
    }
 
}
 
</nowiki></pre>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 200  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A400-MalformedRequest|#400-MalformedRequest]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],[[#A423-NetworkNotReady|#430-PortNotFound]] </span> <span id="op11"></span><<Anchor([[PutPortAttachment]])>>  </span>
 
 
 
----
 
=== Attach resource to port ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| PUT
 
| /tenants/{tenant-id}/networks/{network-id}/ports/{port-id}/attachment
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The request body for this network should contain a reference to the resource to plug into the logical port. Plugged resources can either be managed by or external to Quantum. In both cases, the request body will contain an identifier for that resource. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation asynchronously plugs a resource, or attachment, into the logical port specified in the request URL.  A resource is typycally a virtual network interface belonging to a VM instance. Different kinds of resources can be defined in the future. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The request will be first validated by Quantum and then dispatched to the plugin. As the request is asynchronous, control is immediately returned to the caller.  </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">The validation can fail if: </span></span>
 
 
 
* <span style="font-size: larger"><span style="font-size: smaller">The attachment is already plugged somewhere else;  </span></span>
 
* <span style="font-size: larger"><span style="font-size: smaller">There is already another attachment plugged into the specified logical port.  </span></span>
 
* The port in which the attachment is going to be plugged is administratively down (state = DOWN)
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">If the validation phase fails, the attachment object is not created at all, and an error is returned to the caller. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml
 
 
 
<attachment id="test_interface_identifier"/>
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json
 
 
 
{
 
"attachment":
 
    {
 
        "id": "test_interface_identifier"
 
    }
 
}
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 204 </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]], [[#A400-BadRequest|#400-BadRequest]], [[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],</span></span><span style="font-size: larger"><span style="font-size: smaller">[[#A430-PortNotFound|#430-PortNotFound]],[[#A432-PortInUse|#432-PortInUse]],[[#A433-PortIsDown|#433-PortIsDown]],[[#A440-AlreadyAttached|#440-AlreadyAttached]], [[#A441-AttachmentNotReady|#441-AttachmentNotReady]] </span> <span id="op12"></span><<Anchor([[DeletePortAttachment]])>>  </span>
 
 
 
----
 
=== Remove attachment from port ===
 
----
 
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb
 
| URI
 
|-
 
| DELETE
 
| /tenants/{tenant-id}/networks/{network-id}/ports/{port-id}/attachment
 
|}
 
 
 
+~
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation does not require a request body. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">This operation asynchronously removes an attachment from a logical port.  This operation cannot be undone. </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Sample Request/Response:'' </span></span>
 
 
 
'''XML'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
'''JSON'''
 
 
 
Request:
 
 
 
 
 
<pre><nowiki>
 
DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json
 
</nowiki></pre>
 
 
 
Response:
 
 
 
''No data returned in response body''
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Normal Response code: 204 </span></span>
 
 
 
<span style="font-size: larger"><span style="font-size: smaller">Error response code(s):  [[#A470-ServiceUnavailable|#470-ServiceUnavailable]],[[#A401-Unauthorized|#401-Unauthorized]],[[#A420-NetworkNotFound|#420-NetworkNotFound]],</span></span><span style="font-size: larger"><span style="font-size: smaller">[[#A430-PortNotFound|#430-PortNotFound]], [[#A433-PortIsDown|#433-PortIsDown]], [[#A441-AttachmentNotReady|#441-AttachmentNotReady]] </span></span>
 

Latest revision as of 23:30, 17 February 2013

Please see: http://docs.openstack.org/api/openstack-network/2.0/content/index.html