Maven Example Documentation

JSON and XML Response Formats
Format	Accept Header	Query Extension	Default
JSON	application/json	.json	No
XML	application/xml	.xml	Yes

Fault Elements and Error Codes
Fault Element	Error Code	Description
BadRequest	400	- Malformed request body. - The Quantum service is unable to parse the contents of the - request body. -
Unauthorized	401	- 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. -
Forbidden	403	- The user does not have the necessary rights - to execute the requested operation -
ItemNotFound	404	- The requested resource does not exist on the Quantum API server -
NetworkNotFound	420	- The specified network has not been created or has been removed. -
NetworkInUse	421	- The specified network has attachments plugged into one or more of its ports. -
PortNotFound	430	- The specified port has not been created or has been removed. -
RequestedStateInvalid	431	- Indicates a request to change port to an administrative - state not currently supported. -
PortInUse	432	- The specified port cannot be removed as there is an attachment plugged in it. -
AlreadyAttached	440	- Attachment is already plugged into another port. -

- Networks - - This section describes the operations exposed by Quantum API for - manipulating network resources. - -

- List Networks - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks - - List summary of networks configured in Quantum for - a given tenant, identified by tenant-id - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403) - - - 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. - - - - TenantId is a unique tenant - identifier. The Quantum service does not directly - manages tenants. Tenant management should be - performed by the identity service - - - This operation does not require a request body. - - Networks List Request/Response (XML) - Request: - -GET /tenants/XYZ/networks.xml - - Response: - - - - - - Networks List Request/Response (JSON) - Request: - -GET /tenants/XYZ/networks.json - - Response: - - - -

- List Networks Details - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/detail - - List more detailed information about networks - configured in Quantum for a given tenant, - identified by tenant-id - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403) - - - This operation returns the list of all networks currently - defined in Quantum; for each network, its identifier - and name are returned. - - This operation does not require a request body. - - Networks List Request/Response (XML) - Request: - -GET /tenants/XYZ/networks/detail.xml - - Response: - - - - - - Networks List Request/Response (JSON) - Request: - -GET /tenants/XYZ/networks/detail.json - - Response: - - - -

- Show Network - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/{network-id} - - List information for a specific network, - identified by network-id, - for a given tenant, identified by tenant-id. - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - - - This operation returns the identifier and the name for a - specific network configured in Quantum. - - This operation does not require a request body. - - Show Network Request/Response (XML) - Request: - -GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.xml - - Response: - - - - - - Show Network Request/Response (JSON) - Request: - -GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3.json - - Response: - - - -

- Show Network Details - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/{network-id}/detail - - List detailed information for a specific network, - identified by network-id, - for a given tenant, identified by tenant-id. - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - - - 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. - - If no attachment is plugged into a port, the response will - not include an attachment child element for that - port. - - This operation does not require a request body. - - Show Network Detail Request/Response (XML) - Request: - -GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3/detail.xml - - Response: - - - - - Show Network Detail Request/Response (JSON) - Request: - -GET /tenants/XYZ/networks/8bec1293-16bd-4568-ba75-1f58bec0b4c3/detail.json - - Response: - - - -

- Create Network - - - - Verb - URI - Description - - - - - &POST; - /tenants/{tenant-id}/networks - - Creates a new logical layer-2 network for the - tenant identified by tenant-id - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - BadRequest (400) - Unauthorized (401), - Forbidden (403), - - - This operation 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. 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. - - If the validation phase fails, the network object is not - created at all, and a 400 error is returned to the caller. - - - - The Quantum API v1.0 does not provide an interface - for checking the progress of asynchronous operations - performed by plugins. - - - This will be addressed in future releases of the - Quantum API. - - - - The body for this request must contain a Network object - specifying a symbolic name for the network. - - - Create Network Request/Response (XML) - Request: - -POST /tenants/XYZ/networks.xml - - - - Response: - - - - - Create Network Request/Response (JSON) - Request: - -POST /tenants/XYZ/networks.json - - - - Response: - - - -

- Update Network - - - - Verb - URI - Description - - - - - &PUT; - /tenants/{tenant-id}/networks/{network-id} - - Renames the network identified by - network-id for the - tenant identified by tenant-id - - - - - - Normal Response Code(s): - 204 - - - Error Response Code(s): - BadRequest (400) - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420) - - - This operation renames a Quantum network using the data - provided in the request body. - - - 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. - - - Update Network Request/Response (XML) - Request: - -PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml - - - - Response: - No data returned in response body - - - Update Network Request/Response (JSON) - Request: - -PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json - - - - Response: - No data returned in response body - -

- Delete Network - - - - Verb - URI - Description - - - - - &DELETE; - /tenants/{tenant-id}/networks/{network-id} - - Destroys the network identified by - network-id for the - tenant identified by tenant-id - - - - - - Normal Response Code(s): - 204 - - - Error Response Code(s): - BadRequest (400) - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - NetworkInUse (421) - - - 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. - - - 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. - - Please note that this operation cannot be undone. - - - This operation does not require a request body. - - - Delete Network Request/Response (XML) - Request: - -DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.xml - - Response: - No data returned in response body - - - Update Network Request/Response (JSON) - Request: - -DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1.json - - Response: - No data returned in response body - -

- Ports - - This section describes the operations exposed by Quantum API for - manipulating port resources. - -

- List Ports - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/ - {network-id}/ports - - Lists all the ports currently defined for a Quantum network, - identified by network-id - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420) - - - 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. - - This operation does not require a request body. - - Port List Request/Response (XML) - Request: - -GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.xml - - Response: - - - - - - Port List Request/Response (JSON) - Request: - -GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.json - - Response: - - - -

- List Ports Details - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/ - {network-id}/ports/detail - - Lists detailed information for all the ports currently defined - for the network identified by network-id - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420) - - - 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. - - This operation does not require a request body. - - Port List Details Request/Response (XML) - Request: - -GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/detail.xml - - Response: - - - - - - Port List Details Request/Response (JSON) - Request: - -GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/detail.json - - Response: - - - -

- Show Port - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/ - {network-id}/ports/ - {port-id} - - Retrieves the port - port-id configured for the - network network-id belonging - to the tenant tenant-id. - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - PortNotFound (430) - - - This operation returns the unique identifier and the - current administrative state for a specific port configured - for the network specified in the request URI. - - This operation does not require a request body. - - Show Port Request/Response (XML) - Request: - -GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml - - Response: - - - - - - Show Port Request/Response (JSON) - Request: - -GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json - - Response: - - - -

- Show Port Details - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/ - {network-id}/ports/ - {port-id}/detail - - Retrieves detailed information for the port - port-id configured for the - network network-id belonging - to the tenant tenant-id. - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - PortNotFound (430) - - - This operation provides at least the identifier and the - current administrative state for specific port configured - for a given network. - - If an attachment is plugged into the port, this operation - will return the identifier of the attachment as well. - - This operation does not require a request body. - - Show Port Detail Request/Response (XML) - Request: - -GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855/detail.xml - - Response: - - - - - Show Port Detail Request/Response (JSON) - Request: - -GET /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855/detail.json - - Response: - - - -

- Create Port - - - - Verb - URI - Description - - - - - &POST; - /tenants/{tenant-id}/networks/ - {network-id}/ports - - Creates a port on the network specified - in the request URI, identified by - network-id - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - BadRequest (400), - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - RequestedStateInvalid (431) - - - 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. - - 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 BadRequest error is returned - to the caller. - - The operation returns a port with an identifier, and set its - administrative state set to DOWN, unless a state - has been explicitly specified in the request body. - - 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. - - 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 - DOWN or ACTIVE. - The administrative state should be encapsulated into a Port - object within the request body, as shown in the example below. - - - Create Port Request/Response (XML) - Request: - -POST /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.xml - - - - Response: - - - - - Create Port Request/Response (JSON) - Request: - -POST /tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports.json - - - - Response: - - - -

- Update Port - - - - Verb - URI - Description - - - - - &PUT; - /tenants/{tenant-id}/networks/ - {network-id}/ports/ - {port-id} - - Sets the administrative state for the port - identified by port-id - on the network identified by - network-id - - - - - - Normal Response Code(s): - 204 - - - Error Response Code(s): - BadRequest (400), - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - PortNotFound (430), - RequestedStateInvalid (431) - - - This operation sets the administrative state for a port. - Currently Quantum recognizes two port states: - DOWN and ACTIVE. In the - DOWN state a port will not provide - connectivity to the network. - - This feature allows the tenant the ability to take entities - offline without affecting the logical topology. - - The operation will return the RequestedStateInvalid - error code if the specified administrative state is not either - DOWN or ACTIVE. - - The operation's request body must contain a Port object with - the new administrative state for the port. - - - Set Port State Request/Response (XML) - Request: - -PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml - - - - Response: - No data returned in response body. - - - Set Port State Request/Response (JSON) - Request: - -PUT tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json - - - - Response: - No data returned in response body. - -

- Delete Port - - - - Verb - URI - Description - - - - - &DELETE; - /tenants/{tenant-id}/networks/ - {network-id}/ports/ - {port-id} - - Destroys the port - identified by port-id - on the network identified by - network-id - - - - - - Normal Response Code(s): - 204 - - - Error Response Code(s): - BadRequest (400), - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - PortNotFound (430), - PortInUse (432) - - - 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. - - The operation is not recoverable and will fail if an - attachment is plugged into the port. # - - This operation does not require a request body. - - - Delete Port State Request/Response (XML) - Request: - -DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.xml - - Response: - No data returned in response body. - - - Delete Port State Request/Response (JSON) - Request: - -DELETE tenants/33/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/98017ddc-efc8-4c25-a915-774b2a633855.json - - Response: - No data returned in response body. - -

- Attachments - - This section describes the operations exposed by Quantum API for - manipulating port attachments. - - An attachment is typically a virtual network interface - belonging to a VM instance. Different kinds of resources - can be defined in the future. - -

- Show Attachment for Port - - - - Verb - URI - Description - - - - - &GET; - /tenants/{tenant-id}/networks/ - {network-id}/ports/ - {port-id}/attachment - - Returns the identifier of the attachment plugged - into the specified port, identified by - port-id. - - - - - - Normal Response Code(s): - 200 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - PortNotFound (430) - - - 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. - - 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 attachment element - with no id attribute set. - - This operation does not require a request body. - - Show Attachment (XML) - Request: - -GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml - - Response (attachment set): - - - Response (attachment not set): - - - - - Show Attachment (JSON) - Request: - -GET /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json - - Response (attachment set): - - - Response (attachment not set): - - - -

- Plug Attachment into Port - - - - Verb - URI - Description - - - - - &PUT; - /tenants/{tenant-id}/networks/ - {network-id}/ports/ - {port-id}/attachment - - Plugs a resource, i.e. a virtual network interface - into the port identified by - port-id. - - - - - - Normal Response Code(s): - 204 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - PortNotFound (430), - PortInUse (432), - AlreadyAttached (440) - - - This operation plugs an attachment into the port - specified in the request URL. - - 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. - - The validation can fail if: - - - - - An attachment with the same identifier - is already plugged somewhere else; - - - - - There is already another attachment plugged - into the specified port. - - - - - If the validation phase fails, the attachment is not - created at all, and the appropriate error code is - returned to the caller. - - - 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 attachment element. - - - The request body for this network should contain a reference - to the attachment to plug into the port. - - - Plug Attachment (XML) - Request: - -PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml - - - - Response: - No data returned in response body - - - Plug Attachment (JSON) - Request: - -PUT /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json - - - - Response: - No data returned in response body - -

- Unplug Attachment from Port - - - - Verb - URI - Description - - - - - &DELETE; - /tenants/{tenant-id}/networks/ - {network-id}/ports/ - {port-id}/attachment - - Removes the attachment currently plugged - into the port identified by - port-id. - - - - - - Normal Response Code(s): - 204 - - - Error Response Code(s): - Unauthorized (401), - Forbidden (403), - NetworkNotFound (420), - PortNotFound (430) - - - This operation removes the attachment from the port - specified in the request URI. - - If no attachment is currently plugged into the port, - this operation has no effect. - - - This operation does not require a request body - - - Remove Attachment (XML) - Request: - -DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.xml - - Response: - No data returned in response body - - - Remove Attachment (JSON) - Request: - -DELETE /tenants/XYZ/networks/158233b0-ca9a-40b4-8614-54a4a99d47d1/ports/b832be00-6553-4f69-af33-acd554e36d08/attachment.json - - Response: - No data returned in response body - -

About the XML namespace

lang (as an attribute name)

Notes

space (as an attribute name)

base (as an attribute name)

id (as an attribute name)

Father (in any context at all)

About this schema document

Versioning policy for this schema document

Namespaces

Imports

Includes

Elements

Complex Types

Simple Types

- -



enum values