Jump to: navigation, search

Difference between revisions of "QuantumAPISpec"

(Simply marked up the error response names so that they didn't create false page links.)
(Adjusting wording in Operation description so that it does not necessarily imply the presence of a quantum db)
Line 48: Line 48:
 
| AttachmentsPlugged
 
| AttachmentsPlugged
 
|-
 
|-
−
|<#4F91BD>|423
+
|<#4F91BD>|422
 
|<#4F91BD>|AlreadyAttached
 
|<#4F91BD>|AlreadyAttached
 
|-
 
|-
−
| 424
+
| 423
 
| PortInUse
 
| PortInUse
 
|-
 
|-
−
|<#4F91BD>|500
+
|<#4F91BD>|430
 
|<#4F91BD>|Service Unavailable
 
|<#4F91BD>|Service Unavailable
 
|-
 
|-
−
| 510
+
| 431
 
| PluginFault
 
| PluginFault
 
|}
 
|}
Line 64: Line 64:
  
 
=== List networks ===
 
=== List networks ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 72: Line 72:
 
| /networks  
 
| /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">''Request Body:'' </span></span>
Line 92: Line 91:
  
 
=== List network details ===
 
=== List network details ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 100: Line 99:
 
| /networks/id  
 
| /networks/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">''Request Body:'' </span></span>
Line 120: Line 118:
  
 
=== Create Network ===
 
=== Create Network ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 128: Line 126:
 
| /networks  
 
| /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">''Request Body:'' </span></span>
Line 139: Line 136:
 
~+~-This operation asynchronously creates a Layer-2 network in Quantum based on the information provided in the request body.   
 
~+~-This operation asynchronously creates a Layer-2 network in Quantum based on the information provided in the request body.   
  
−
Quantum validates the request, creates the network object, 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.  
+
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.  
  
 
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.   
 
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.   
Line 152: Line 149:
  
 
=== Update Network ===
 
=== Update Network ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 160: Line 157:
 
| /networks/id  
 
| /networks/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">''Request Body:'' </span></span>
Line 176: Line 172:
  
 
=== Delete Network ===
 
=== Delete Network ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 184: Line 180:
 
| /networks/id  
 
| /networks/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">''Request Body:'' </span></span>
Line 197: Line 192:
 
Logical ports will be destroyed together with the network. The operation is asynchronous.  
 
Logical ports will be destroyed together with the network. The operation is asynchronous.  
  
−
Quantum forwards the request to the plugin, and upon success removes the network object. Callers can check the current status of the operation by performing a GET on networks/id. This operation is not recoverable. -~+~
+
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. This operation is not recoverable. -~+~
  
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
 
<span style="font-size: larger"><span style="font-size: smaller">''Response Codes:'' </span></span>
Line 206: Line 201:
  
 
=== List logical ports for network ===
 
=== List logical ports for network ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 214: Line 209:
 
| /networks/id/ports  
 
| /networks/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">''Request Body:'' </span></span>
Line 232: Line 226:
  
 
=== List port details ===
 
=== List port details ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 240: Line 234:
 
| networks/net_id/ports/port_id  
 
| networks/net_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">''Request Body:'' </span></span>
Line 260: Line 253:
  
 
=== Create Port ===
 
=== Create Port ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 268: Line 261:
 
| /networks/id/ports  
 
| /networks/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">''Request Body:'' </span></span>
Line 277: Line 269:
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
 
<span style="font-size: larger"><span style="font-size: smaller">''Description:'' </span></span>
  
−
~+~-This operation asynchronously creates a port on a Quantum network based on the information provided in the request body.  Quantum validates the request, creates the port object and attaches it to the appropriate network object. The request is then dispatched to the plugin.
+
~+~-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 400 error is returned to the caller. -~+~
 
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 400 error is returned to the caller. -~+~
Line 290: Line 282:
  
 
=== Delete Port ===
 
=== Delete Port ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 298: Line 290:
 
| /networks/net_id/ports/port_id  
 
| /networks/net_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">''Request Body:'' This operation does not require a request body. </span></span>
Line 316: Line 307:
  
 
=== List attachment details for port ===
 
=== List attachment details for port ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 324: Line 315:
 
| /networks/net_id/ports/port_id/attachment  
 
| /networks/net_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">''Request Body:'' </span></span>
Line 347: Line 337:
  
 
=== Attach resource to port ===
 
=== Attach resource to port ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 355: Line 345:
 
| /networks/net_id/ports/port_id/attachment  
 
| /networks/net_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">''Request Body:'' </span></span>
Line 381: Line 370:
  
 
=== Remove attachment from port ===
 
=== Remove attachment from port ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 389: Line 378:
 
| /networks/net_id/ports/port_id/attachment  
 
| /networks/net_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">''Request Body:'' </span></span>
Line 407: Line 395:
  
 
=== Retrieve resources attached to network ===
 
=== Retrieve resources attached to network ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 415: Line 403:
 
| /networks/net_id/attachments  
 
| /networks/net_id/attachments  
 
|}
 
|}
−
 
+
+~
−
-~+~
 
  
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
Line 433: Line 420:
  
 
=== Attach resource to network ===
 
=== Attach resource to network ===
−
~+~-
+
~+
 
{| border="1" cellpadding="2" cellspacing="0"
 
{| border="1" cellpadding="2" cellspacing="0"
 
| Verb  
 
| Verb  
Line 441: Line 428:
 
| /networks/net_id/attachments  
 
| /networks/net_id/attachments  
 
|}
 
|}
−
 
+
+~
−
-~+~
 
  
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>
 
<span style="font-size: larger"><span style="font-size: smaller">''Request Body:'' </span></span>

Revision as of 16:24, 17 May 2011

Quantum API Specification

<<TableOfContents()>>

Introduction

~+~- 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 home page and the Network projects home page.

This document constitutes a first attempt in defining an API for the Quantum service. The operation list cannot be deemed complete, and formats for request and response messages have not yet been defined. Moreover, authentication, authorization, and extension mechanisms, as well as the URL structure, are not defined in this document. -~+~

Since Quantum provides “network connectivity as a service”, this API defines Layer-2 operations only. This document also proposes operations for bridging Quantum networks with external networks, such as a customer-managed network in an on-premise data centre; however, use cases in this area (bridging and federation) should be explored better.

We first introduce the operation list, and then discuss how these operations can be used to accomplish some common use cases.

Glossary

Network
Plugin
VIF
Attachment
Logical Port

Operation List

For each operation, both XML and JSON representation should be assumed. List of error response codes:

Code Name
400 Bad Request
401 Unauthorized
413 OverLimit
421 AttachmentsPlugged
422 AlreadyAttached
423 PortInUse
430 Service Unavailable
431 PluginFault

<<Anchor(GetNetworks)>>

List networks

~+

Verb URI
GET /networks

+~

Request Body:

This operation does not require a request body.

Description:

This operation returns the list of all networks currently defined in Quantum; returned list includes at least the network’s unique identifier.

Response Codes:

~+~-Normal Response code: 200

Error response code(s): 500 Service Unavailable, 401 Unauthorized -~ +~

<<Anchor(GetNetworkDetails)>>

List network details

~+

Verb URI
GET /networks/id

+~

Request Body:

This operation does not require a request body.

Description:

This operation provides detailed output for a specific network configured in Quantum.'

Response Codes:

~+~-Normal Response code: 200

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized -~+~

<<Anchor(PostNetwork)>>

Create Network

~+

Verb URI
POST /networks

+~

Request Body:

The body for this network should contain a symbolic name for the network.

Description:

~+~-This operation asynchronously creates a Layer-2 network in Quantum based on the information provided in the request body.

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.

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.

If the validation phase fails, the network object is not created at all, and a 400 error is returned to the caller. -~+~

Response Codes:

~+~-Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 413 Over Limit -~ <<Anchor(PutNetwork)>> +~

Update Network

~+

Verb URI
PUT /networks/id

+~

Request Body:

The request body for this operation will possibly contain the new symbolic name for the network.

Description: This operation asynchronously updates a network in Quantum according to the information provided in the request body.

Response Codes:

~+~-Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 510 PluginFault -~ <<Anchor(DeleteNetwork)>> +~

Delete Network

~+

Verb URI
DELETE /networks/id

+~

Request Body:

This operation does not require a request body.

Description:

~+~-This operation removes the network specified in the URI. It will fail if an attachment is plugged into anyone of the network’s ports (error code 511). It will not fail instead if logical ports are configured for the network, as long as nothing is plugged into them.

Logical ports will be destroyed together with the network. 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. This operation is not recoverable. -~+~

Response Codes:

~+~-Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 510 PluginFault, 511 AttachmentsPlugged -~ <<Anchor(GetPorts)>> +~

List logical ports for network

~+

Verb URI
GET /networks/id/ports

+~

Request Body:

This operation does not require a request body.

Description:

This operation lists all the ports currently configured for a network. Response should include, for each port, at least its unique identifier (might just be a port number) and the identifier of the attachment plugged into it, if any.

Response Codes:

~+~-Normal Response code: 200

Error response code(s): 500 Service Unavailable, 401 Unauthorized -~ <<Anchor(GetPortDetails)>> +~

List port details

~+

Verb URI
GET networks/net_id/ports/port_id

+~

Request Body:

This operation does not require a request body.

Description:

~+~-This operation provides detailed output for a specific port configured for a given network.

This operation will return all the attributes of the port, including plugin-specific attributes. -~+~

Response Codes:

~+~-Normal Response code: 200

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized -~ <<Anchor(PostPort)>> +~

Create Port

~+

Verb URI
POST /networks/id/ports

+~

Request Body:

The request body is not mandatory.

Description:

~+~-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 400 error is returned to the caller. -~+~

Response Codes:

~+~-Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 413 Over Limit -~

<<Anchor(DeletePort)>> +~

Delete Port

~+

Verb URI
DELETE /networks/net_id/ports/port_id

+~

Request Body: This operation does not require a request body.

Description:

~+~-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.

The operation is not recoverable and will fail if an attachment is plugged into the port. -~+~

Response Codes:

~+~-Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 510 PluginFault, 511 AttachmentsPlugged. -~ <<Anchor(GetPortAttachment)>> +~

List attachment details for port

~+

Verb URI
GET /networks/net_id/ports/port_id/attachment

+~

Request Body:

This operation does not require a request body.

Description:

~+~-This operation returns configuration details for the attachment plugged into the port specified in the request URI.

This information might include:

  • Type of the attachment (e.g.: virtual network interface, bridge device);
  • A reference to the resource being attached (If managed by Quantum);
  • A reference to an external resource being attached (If not managed by Quantum); -~+~

Response Codes:

~+~-Normal Response code: 200

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorize -~ <<Anchor(PutPortAttachment)>> +~

Attach resource to port

~+

Verb URI
PUT /networks/net_id/ports/port_id/attachment

+~

Request Body:

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.

Description:

~+~-This operation asynchronously plugs a resource, or attachment, into the logical port specified in the request URL. A resource can be either a virtual network interface belonging to a VM instance, or any kind of device or service which can be plugged into the Quantum network in order to provide different services, such as IP addressing management. Different kinds of resources can be defined in the future.

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. Progress of the operation can then be checked by querying the attachment (or the logical port) with a GET request.

The validation can fail if:

  • The attachment is already plugged somewhere else;
  • There is already another attachment plugged into the specified logical port.

If the validation phase fails, the attachment object is not created at all, and a 400 error is returned to the caller. -~+~

Response Codes:

~+~-Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 413 Over Limit, 423 AlreadyAttached, 423 PortInUse, 510 PluginFault -~ <<Anchor(DeletePortAttachment)>> +~

Remove attachment from port

~+

Verb URI
DELETE /networks/net_id/ports/port_id/attachment

+~

Request Body:

This operation does not require a request body.

Description:

This operation asynchronously removes an attachment from a logical port. This operation cannot be undone.

Response Codes:

~+~-Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 413 Over Limit, 510 PluginFault -~ <<Anchor(GetNetworkAttachments)>> +~

Retrieve resources attached to network

~+

Verb URI
GET /networks/net_id/attachments

+~

Request Body:

This operation does not require a request body.

Description:

This operation return a list of resource currently attached to the virtual network specified in the URI. For each resource, the returned list should specify at least the identifier of the resource and the identifier of the port in which the resource is currently plugged.

Response codes:

~+~-Normal Response code: 200

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized -~ <<Anchor(PostNetworkAttachment)>> +~

Attach resource to network

~+

Verb URI
POST /networks/net_id/attachments

+~

Request Body:

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.

Description:

~+~-This operation asynchronously plugs a resource, or attachment, into the logical port specified in the request URL. A resource can be either a virtual network interface belonging to a VM instance, or any kind of device or service which can be plugged into the Quantum network in order to provide different services, such as IP addressing management. Different kinds of resources can be defined in the future.

This operation is very similar to “attach resource to port”, with the only exception that a logical port is not specified in this case. Quantum plugins can either use a free port on the network, or create a new logical port, and then plug the resource into it.

The identifier of the logical port where the resource has been plugged should be returned to the caller. -~+~

~+~-Response Codes: Normal Response code: 202

Error response code(s): 500 Service Unavailable, 400 Bad Request, 401 Unauthorized, 413 Over Limit, 423 AlreadyAttached, 424 PortInUse, 510 PluginFault -~ +~

Retrieved from "https://wiki.openstack.org/w/index.php?title=QuantumAPISpec&oldid=7989"