GET'> PUT'> POST'> DELETE'> '> '> ]> Quantum API v2.0 2011 2012 OpenStack Quantum API v2.0 OpenStack Quantum (virtual network service) 2012-08-17 Copyright details are filled in by the template. This document is intended for software developers who develop applications by using the OpenStack &APIv2;. 2012-08-17 First edition of this book. The Quantum project provides virtual networking services among devices that are managed by the OpenStack compute service. The &APIv2; combines the Quantum API v1.1 with some essential Internet Protocol Address Management (IPAM) capabilities from the Melange API. These IPAM capabilities enable you to: Associate IP address blocks and other network configuration settings required by a network device, such as a default gateway and dns-servers settings, with a Quantum network. Allocate an IP address from a block and associate it with a device that is attached to the network through a Quantum port. To do this, the &APIv2; introduces the subnet entity. A subnet can represent either an IP version 4 or version 6 address block. Each Quantum network commonly has one or more subnets. When you create a port on the network, an available fixed IP address is allocated to it from one the designated subnets for each IP version. When you delete the port, the allocated addresses return to the pool of available IPs on the subnet. &APIv2; users can choose a specific IP address from the block or let Quantum choose the first available IP address. The Quantum API v1.x was removed from the source code tree. To use the Quantum API v1.x, install an earlier release of Quantum.

Term Description CRUD In computer programming, create, read, update, and delete (CRUD) functions are the basic functions of persistent storage. entity Any piece of hardware or software that wants to connect to the network services provided by Quantum. An entity can use Quantum network services by implementing a VIF. IPAM Internet Protocol Address Management (IPAM) is a means of planning, tracking, and managing the Internet Protocol (IP) address space that is used in a network. layer-2 network A virtual Ethernet network that is managed by the Quantum service. Currently, Quantum manages only Ethernet networks. network An isolated virtual layer-2 broadcast domain that is typically reserved for the tenant who created it unless the network is configured to be shared. Tenants can create multiple networks until they reach the thresholds specified by per-tenant quotas. plugin A software component that implements &APIv2;. port A virtual switch port on a logical network switch. Virtual instances attach their interfaces into ports. The logical port also defines the MAC address and the IP addresses to be assigned to the interfaces plugged into them. When IP addresses are associated to a port, this also implies the port is associated with a subnet, as the IP address was taken from the allocation pool for a specific subnet. subnet An IP address block that can be used to assign IP addresses to virtual instances. Each subnet must have a CIDR and must be associated with a network. IPs can be either selected from the whole subnet CIDR or from allocation pools that can be specified by the user. VM A virtual machine (VM) is a completely isolated guest operating system installation within a normal host operating system.

The high-level task flow for Quantum networking is as follows: The tenant creates a network. For example, the tenant creates the net1 network. The tenant associates a subnet with that network. For example, the tenant associates the 10.0.0.0/24 subnet with the net1 network. The tenant boots a virtual machine (VM) and specifies a single NIC that connects to the network. For example:$ nova boot --image image_name --nic net-id=id_of_net1 server_name Nova contacts Quantum and creates the port1 port on the net1 network. Quantum assigns an IP address to the port1 port. Quantum chooses the IP address. The tenant deletes the VM. Nova contacts Quantum and deletes the port1 port. The allocated IP address is returned to the pool of available IP addresses.

Virtual networking services are implemented through a plugin. A plugin can use different techniques and technologies to provide isolated virtual networks to tenants. A plugin also provides other services, such as IP address management. Because each plugin implements all the operations included in &APIv2;, you do not need to be concerned about which plugin is used. However, some plugins might expose additional capabilities through API extensions, which are discussed in this document. For more information about the extensions exposed by a particular plugin, see the plugin documentation.

&APIv2; manages the following entities: Network. An isolated virtual layer-2 domain. A network can also be a virtual, or logical, switch. See . Subnet. An IP version 4 or version 6 address block from which IP addresses that are assigned to VMs on a specified network are selected. See . Port. A virtual, or logical, switch port on a specified network. See . These entities have auto-generated unique identifiers and support basic create, read, update, and delete (CRUD) functions with the &POST;, &GET;, &PUT;, and &DELETE; verbs.

A network is an isolated virtual layer-2 broadcast domain that is typically reserved for the tenant who created it unless the network is configured to be shared. Tenants can create multiple networks until they reach the thresholds specified by per-tenant quotas. See . In the &APIv2;, the network is the main entity. Ports and subnets are always associated with a network. The following table describes the attributes for network objects.

Network Attributes

Attribute	Type	Required	CRUD C. Use the attribute in create operations. R. This attribute is returned in response to show and list operations. U. You can update the value of this attribute. D. You can delete the value of this attribute.	Default Value	Validation Constraints	Notes
id	uuid-str	N/A	R	generated	N/A	UUID for the network.
name	String	No	CRU	None	N/A	Human-readable name for the network. Might not be unique.
admin_state_up	Bool	No	CRU	true	{true|false}	The administrative state of network. If false (down), the network does not forward packets.
status	String	N/A	R	N/A	N/A	Indicates whether network is currently operational. Possible values include: ACTIVE DOWN BUILD ERROR Plugins might define additional values.
subnets	list(uuid-str)	No	R	Empty List	N/A	subnets associated with this network.
permissions	octal(3)	No	CR The &APIv2; currently ignores group permissions, and executable bits. Write access to world, even if granted by the user, is currently ignored by the Quantum API. The full permission mask has been provided for compatibility with future implementations.	rw- --- ---	3-octal digit string or permission string in the rwxrwxrwx form. The &APIv2; also allows the symbolic string private and public for the permissions string. Private corresponds to 0600 or rw- --- ---, whereas Public corresponds to 0644 or rw-r--r--.	Specifies access rights on the network object for owner, group, and world
tenant_id	uuid-str	No If Quantum is not running with the Keystone Identity service, the tenant_id attribute is required.	CR	N/A	UUID_PATTERN	Owner of network. Only admin users can specify a tenant_id other than its own.

A subnet represents an IP address block that can be used to assign IP addresses to virtual instances. Each subnet must have a CIDR and must be associated with a network. IPs can be either selected from the whole subnet CIDR or from allocation pools that can be specified by the user. A subnet can also optionally have a gateway, a list of dns name servers, and host routes. This information is pushed to instances whose interfaces are associated with the subnet.

Subnet Attributes

Attribute	Type	Required	CRUD C. Use the attribute in create operations. R. This attribute is returned in response to show and list operations. U. You can update the value of this attribute. D. You can delete the value of this attribute.	Default Value	Validation Constraints	Notes
id	uuid-str	N/A	R	generated	N/A	UUID representing the subnet
network_id	uuid-str	Yes	CR	N/A	network this subnet is associated with.
ip_version	int	Yes	CR	4	{ 4 | 6 }	IP version
cidr	string	Yes	CR	N/A	valid cidr in the form <network_address>/<prefix>	cidr representing IP range for this subnet, based on IP version
gateway_ip	string	No	CRUD	first address in cidr	Valid IP address	default gateway used by devices in this subnet
dns_nameservers	list(str)	No	CRU	None	No constraint	DNS name servers used by hosts in this subnet.
allocation_pools	list(dict)	No	CR	Every address in cidr, excluding gateway_ip if configured	star/end of range must be valid ip	Sub-ranges of cidr available for dynamic allocation to ports [ { "start": "10.0.0.2", "end": "10.0.0.254"} ]
host_routes	list(dict)	No	CRU	default route to gateway_ip	TBD	Routes that should be used by devices with IPs from this subnet (not including local subnet route).
tenant_id	uuid-str	No If Quantum is not running with the Keystone Identity service, the tenant_id attribute is required.	CR	N/A	UUID_PATTERN	Owner of network. Only admin users can specify a tenant_id other than its own.

A port represents a virtual switch port on a logical network switch. Virtual instances attach their interfaces into ports. The logical port also defines the MAC address and the IP address(es) to be assigned to the interfaces plugged into them. When IP addresses are associated to a port, this also implies the port is associated with a subnet, as the IP address was taken from the allocation pool for a specific subnet.

Port Attributes

Attribute	Type	Required	CRUD C. Use the attribute in create operations. R. This attribute is returned in response to show and list operations. U. You can update the value of this attribute. D. You can delete the value of this attribute.	Default Value	Validation Constraints	Notes
id	uuid-str	N/A	R	generated	N/A	UUID for the port.
network_id	uuid-str	Yes	CR	N/A	existing network identifier	Network that this port is associated with.
admin_state_up	bool	No	CRU	true	{true|false}	Administrative state of port. If false (down), port does not forward packets.
status	string	N/A	R	N/A	N/A	Indicates whether network is currently operational. Possible values include: ACTIVE DOWN BUILD ERROR Plugins might define additional values.
mac_address	string	No	CR	generated	valid MAC in 6-octet form separated by colons	Mac address to use on this port.
fixed_ips	list(dict)	No	CRU	automatically allocated from pool	Valid IP address and existing subnet identifier	Specifies IP addresses for the port thus associating the port itself with the subnets where the IP addresses are picked from
host_routes	list(dict)	No	CR	Empty list	TBD	list of routes to be used with this port. In case of overlap, overrides routes specified for the subnets associated with this port.
device_id	str	No	CRUD	None	No constraint	identifies the device (e.g., virtual server) using this port.
tenant_id	uuid-str	No If Quantum is not running with the Keystone Identity service, the tenant_id attribute is required.	CR	N/A	UUID_PATTERN	Owner of network. Only admin users can specify a tenant_id other than its own.

The &APIv2; is a ReSTful HTTP service that uses all aspects of the HTTP protocol including methods, URIs, media types, response codes, and so on. Providers can use existing features of the protocol including caching, persistent connections, and content compression. For example, providers who employ a caching layer can respond with a 203 code instead of a 200 code when a request is served from the cache. Additionally, providers can offer support for conditional &GET; requests by using ETags, or they may send a redirect in response to a &GET; request. Create clients so that these differences are accounted for.

The &APIv2; uses the Keystone Identity Service as the default authentication service. When Keystone is enabled, users that submit requests to the Quantum service must provide an authentication token in X-Auth-Token request header. You obtain the token by authenticating to the Keystone endpoint. For more information about Keystone, see the OpenStack Identity Developer Guide. When Keystone is enabled, the tenant_id attribute is not required in create requests because the tenant ID is derived from the authentication token. The default authorization settings allow only administrative users to create resources on behalf of a different tenant. Quantum uses information received from Keystone to authorize user requests. Quantum handles the following types of authorization policies: Operation-based policies Specify access criteria for specific operations, possibly with fine-grained control over specific attributes. Resource-based policies Access a specific resource. Permissions might or might not be granted depending on the permissions configured for the resource. Currently available for only the network resource. The actual authorization policies enforced in Quantum might vary from deployment to deployment.

The &APIv2; supports both the JSON and XML data serialization formats. The format for both the request and the response can be specified either using the Content-Type header, the Accept header or adding an .xml or .json extension to the request URI. If conflicting formats are specified in headers and/or format extensions, the latter takes precedence. XML is currently the default format for both requests and responses.

JSON and XML Response Formats

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

The OpenStack Quantum API supports the JSON data format. The format for both the request and the response can be specified either using the Accept header or adding the .json extension to the request URI. Request: POST /v1.0/tenants/tenantX/networks HTTP/1.1 Host 127.0.0.1:9696 Content-Type application/json Accept application/json Content-Length 57 Response: HTTP/1.1 200 Accepted Content-Type application/json Content-Length 204

The &APIv2; supports filtering based on all top level attributes of a resource. Filters are applicable to all list requests. For example, the following request returns all networks named foobar: GET /v2.0/networks?name=foobar When you specify multiple filters, the &APIv2; returns only objects that meet all filtering criteria. The operation applies an AND condition among the filters. Quantum does not offer an OR mechanism for filters. Alternatively, you can issue a distinct request for each filter and build a response set from the received responses on the client-side. By default, Quantum returns all attributes for any show or list call. The &APIv2; has a mechanism to limit the set of attributes returned. For example, return id. You can use the field query parameter to control the attributes returned from the &APIv2;. For example, the following request returns only id and name for each network: GET /v2.0/networks.json?fields=id&fields=name

The &APIv2; presents a logical model of network connectivity consisting of networks, ports, and subnets. It is up to the Quantum plugin to communicate with the underlying infrastructure to ensure packet forwarding is consistent with the logical model. A plugin might perform these operations asynchronously. When an API client modifies the logical model by issuing an HTTP &POST;, &PUT;, or &DELETE; request, the API call might return before the plugin modifies underlying virtual and physical switching devices. However, an API client is guaranteed that all subsequent API calls properly reflect the changed logical model. For example, if a client issues an HTTP &PUT; request to set the attachment for a port, there is no guarantee that packets sent by the interface named in the attachment are forwarded immediately when the HTTP call returns. However, it is guaranteed that a subsequent HTTP &GET; request to view the attachment on that port returns the new attachment value. You can use the status attribute with the network and port resources to determine whether the Quantum plugin has successfully completed the configuration of the resource.

The &APIv2; enables you to create several objects of the same type in the same API request. Bulk create operations use exactly the same API syntax as single create operations except that you specify a list of objects rather than a single object in the request body. Bulk operations are always performed atomically, meaning that either all or none of the objects in the request body are created. If a particular plugin does not support atomic operations, the &APIv2; emulates the atomic behavior so that users can expect the same behavior regardless of the particular plugin running in the background. Quantum might be deployed without support for bulk operations and when the client attempts a bulk create operation, a 400 Bad Request error is returned. For information about how to submit bulk requests to the &APIv2;, see , , and .

[tbd] Yong to contribute

[tbd] Yong to contribute

The &APIv2; is extensible. The purpose of &APIv2; extensions is to: Introduce new features in the API without requiring a version change. Introduce vendor-specific niche functionality. Act as a proving ground for experimental functionalities that might be included in a future version of the API. To programmatically determine which extensions are available, issue a &GET; request on the v2.0/extensions URI. To query extensions individually by unique alias, issue a &GET; request on the /v2.0/extensions/alias_name URI. Use this method to easily determine if an extension is available. If the extension is not available, a 404 itemNotFound response is returned. You can extend existing core API resources with new actions or extra attributes. Also, you can add new resources as extensions. Extensions usually have tags that prevent conflicts with other extensions that define attributes or resources with the same names, and with core resources and attributes. Because an extension might not be supported by all plugins, the availability of an extension varies with deployments and the specific plugin in use.

The &APIv2; returns an error response if a failure occurs while processing a request. Quantum uses only standard HTTP error codes. 4xx errors indicate problems in the particular request being sent from the client. Error Description 400 Bad Request Malformed request URI or body Requested admin state invalid Invalid values entered Bulk operations disallowed 404 Not Found Non existent URI Resource not found 409 Conflict Port configured on network IP allocated on subnet Conflicting IP allocation pools for subnet 422 Unprocessable Entity Validation failed Method not allowed for request body (such as trying to update attributes that can be specified at create-time only) 500 Internal server error Internal Quantum error 503 Service unavailable Failure in Mac address generation Users submitting requests to the &APIv2; might also receive the following errors: 401 Unauthorized. Credentials that were not valid were provided. if invalid credentials are provided 403 Forbidden - If the user cannot access a specific resource or perform the requested operation.

Use the &APIv2; to manage network resources. Verb URI Description &GET; /networks Lists a summary of all networks defined in Quantum that are accessible to the tenant who submits the request. &GET; /networks/network_id Lists detailed information for the specified network ID. &POST; /networks Creates a new Quantum network. &PUT; /networks/network-id Updates the specified network. &DELETE; /networks/network-id Destroys the specified network and all associated resources.

Verb URI Description &GET; /networks Lists a summary of all networks defined in Quantum that are accessible to the tenant who submits the request. Normal Response Code: 200 Error Response Codes: Bad Request (400), Unauthorized (401) Lists a summary of all networks defined in Quantum that are accessible to the tenant who submits the request. The list provides the unique ID for each network. This operation does not require a request body, unless the Quantum server is running without Keystone integration. This operation returns a response body. GET /v2.0/networks Accept: application/json

Verb URI Description &GET; /networks/network_id Lists detailed information for the specified network ID. Normal Response Code: 200 Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404) This operation returns the status, subnets, name, admin state, tenant ID, and ID for the specified network ID. This operation does not require a request body. This operation returns a response body. GET /v2.0/networks/afc75773-640e-403c-9fff-62ba98db1f19 Accept: application/json

Verb URI Description &POST; /networks Creates a new Quantum network. Normal Response Code: 200 Error Response Codes: Bad Request (400) Unauthorized (401) This operation requires a request body. The request body must contain a network object that specifies a symbolic name for the network. This operation returns a response body. POST v2.0/networks.json Content-Type: application/json Accept: application/json

This operation enables you to create several networks in a single request. This operation requires a request body. This operation returns a response body. Specify a list of networks in the request body, as shown in the following example: POST v2.0/networks.json Content-Type: application/json Accept: application/json { "networks": [ { "name": "sample_network_1", "admin_state_up": false }, { "name": "sample_network_2", "admin_state_up": false }] } The bulk create operation is always atomic. Either all or no networks in the request body are created. You can use the permissions attribute to create a public network. A public network can be shared with other tenants. This attribute enables you to specify file system-like permissions on Quantum resources. However, &APIv2; currently supports creating networks that are shared with every other tenant. To do so, set the permissions attribute to 0644 or rw- r-- r--. Control of the permissions attribute could reserved to only specific users, such as administrators. In this case, regular users who try to create a network with a permissions setting that is different from the default value receive a 403 Forbidden error.

Verb URI Description &PUT; /networks/network-id Updates the specified network. Normal Response Code: 200 Error Response Codes: Bad Request (400) Unauthorized (401), Forbidden (403) Not Found (404), Unprocessable Entity (422) This operation requires a request body. You can set the following attributes in the request body:

Update Network Request Body Attributes

Attribute	Description
name	The name for the network.
admin_state_up	Specifies whether the admin state is up or down. Set to true for up and false for down. If down, the network does not forward packets.

You cannot update the status, tenant_id, or id attributes. If you try to update these attributes, a 422 Unprocessable Entity error is returned. This operation returns a response body. Update operations in Quantum adopt patch semantics. This implies that the &APIv2; does not require the user to send the whole resource to be updated, but just the attributes that the user wishes to update, as shown in the following example. PUT /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766.json Content-Type: application/json Accept: application/json { "network": { "name": "updated_name" } } status: 200 content-length: 192 content-type: application/json { "network": { "status": "ACTIVE", "subnets": [], "name": "updated_name", "admin_state_up": false, "shared": false, "tenant_id": "c1210485b2424d48804aad5d39c61b8f", "id": "fc68ea2c-b60b-4b4f-bd82-94ec81110766" } }

Verb URI Description &DELETE; /networks/network-id Deletes the specified network and all associated resources. Normal Response Code: 204 Error Response Codes: Bad Request (400) Unauthorized (401), Forbidden (403), Not Found (404), Network In Use (409) This operation deletes a Quantum network and its associated subnets provided that no port is currently configured on the network. If ports are still configured on the network that you want to delete, a 409 Network In Use error is returned. This operation does not require a request body. This operation does not return a response body. DELETE /v2.0/networks/fc68ea2c-b60b-4b4f-bd82-94ec81110766 Content-Type: application/json Accept: application/json status: 204

Use the &APIv2; to manage subnet resources. Verb URI Description &GET; /subnets Lists all subnets that are accessible to the tenant who submits the request. &GET; /subnets/subnet_id Lists detailed information for the specified subnet. &POST; /subnets Creates a subnet on the specified network. &PUT; /subnets/subnet-id Updates the specified subnet. &DELETE; /subnets/subnet-id Removes the specified subnet.

Verb URI Description &GET; /subnets Lists all subnets that are accessible to the tenant who submits the request. Normal Response Code: 200 Error Response Codes: Unauthorized (401) This operation returns a list of subnets objects the tenant has access to. Default policy settings returns exclusively subnets owned by the tenant submitting the request, unless the request is submitted by an user with administrative rights. You can control which attributes are returned by using the fields query parameter. You can filter results by using query string parameters. See . This operation does not require a request body. This operation returns a response body. GET v2.0/subnets.json Accept: application/json

Verb URI Description &GET; /subnets/subnet-id Gets information about a specified subnet. Normal Response Code: 200 Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404) This operation returns data about the subnet specified in the request URI. You can control which attributes are returned by using the fields query parameter, as discussed in . This operation does not require a request body. This operation returns a response body. GET /v2.0/subnets/4156c7a5-e8c4-4aff-a6e1-8f3c7bc83861 Accept: application/json status: 200 content-length: 309 content-type: application/json

Verb URI Description &POST; /subnets Creates a subnet on the specified network. Normal Response Code: Created (201) Error Response Codes: Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404) This operation creates a new subnet on the specified network. The network ID, network_id, is required. You must also specify the cidr attribute for the subnet, in the form: network_address/prefixThe remaining attributes are optional. By default, Quantum creates IP v4 subnets. To create an IP v6 subnet, you must specify the value 6 for the ip_version attribute in the request body. Quantum does not try to derive the correct IP version from the provided CIDR. If the parameter for the gateway address, gateway_ip, is not specified, Quantum allocates an address from the cidr for the gateway for the subnet. To specify a subnet without a gateway, specify the value none for the gateway_ip attribute in the request body. If allocation pools attribute, allocation_pools, is not specified, Quantum automatically allocates pools for covering all IP addresses in the CIDR, excluding the address reserved for the subnet gateway. Otherwise, you can explicitly specify allocation pools as shown in the following example. POST /v2.0/subnets Content-Type: application/json Accept: application/json { "subnet": { "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc", "ip_version": 4, "cidr": "10.0.3.0/24", "allocation_pools": [{"start": "10.0.3.20", "end": "10.0.3.150"}] } }

This operation requires a request body. This operation returns a response body. This operation enables you to create several subnets in a single request. Specify a list of subnets in the request body, as shown in the following example: POST /v2.0/subnets Content-Type: application/json Accept: application/json { "subnets": [ { "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc", "ip_version": 4, "cidr": "10.0.4.0/24", } { "network_id": "ed2e3c10-2e43-4297-9006-2863a2d1abbc", "ip_version": 4, "cidr": "10.0.5.0/24", } ] } The bulk create operation is always atomic. Either all subnets or no subnets in the request body are created.

Verb URI Description &PUT; /subnets/subnet-id Updates the specified subnet. Normal Response Code: Ok (200) Error Response Codes: Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Unprocessable Entity (422) This operation updates the specified subnet. Some attributes, such as IP version (ip_version), CIDR (cidr), and IP allocation pools (allocation_pools) cannot be updated. Attempting to update these attributes results in a 422 Unprocessable Entity error. This operation requires a request body. This operation returns a response body. Update operations in Quantum adopt patch semantics. This implies that the &APIv2; does not require you to send the whole resource to be updated, but just the attributes that you wish to update, as shown in the following example. PUT /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031 Content-Type: application/json Accept: application/json { "subnet": { "gateway_ip": "10.0.3.254", "name": "new_name" } }

Verb URI Description &DELETE; /subnets/subnet-id Removes the specified subnet. Normal Response Code: 204 Error Response Codes: Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Conflict (409) This operation removes a subnet from a Quantum network. The operation fails if IP addresses from the subnet that you want to delete are still allocated. This operation does not require a request body. This operation does not return a response body. DELETE /v2.0/subnets/9436e561-47bf-436a-b1f1-fe23a926e031 Accept: application/json Status: 204

Use the &APIv2; to manage port resources. Verb URI Description &GET; /ports Lists all ports to which the tenant has access. &GET; /ports/port_id Shows information for the specified port. &POST; /ports Creates a new port for the specified network. &PUT; /ports/port-id Updates the specified port. &DELETE; /ports/port-id Removes the specified port.

Verb URI Description &GET; /ports Lists all ports to which the tenant has access. Normal Response Code: 200 Error Response Codes: Unauthorized (401) This operation returns a list of ports to which the tenant has access. Default policy settings return only those subnets that are owned by the tenant who submits the request, unless the request is submitted by an user with administrative rights. Users can control which attributes should be returned by using the fields query parameter. Additionally, you can filter results by using query string parameters. This operation does not require a request body. This operation returns a response body. GET /v2.0/ports.json HTTP/1.1 content-type: application/json accept: application/json Response:

Verb URI Description &GET; /ports/port-id Shows information for the specified port. Normal Response Code: 200 Error Response Codes: Bad Request (400), Unauthorized (401), Not Found (404) This operation returns information for the port specified in the request URI. This operation does not require a request body. This operation returns a response body. GET /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json accept: application/json Response:

Verb URI Description &POST; /ports Creates a port on the specified network. Normal Response Code: 201 Error Response Codes: Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Conflict (409) This operation creates a new Quantum port. The network where the port is created must be specified in the network_id attribute in the request body. You can also specify the following optional attributes: A symbolic name for the port MAC address Administrative state. Set to true for up, and false for down. Fixed IPs If you specify just a subnet ID, Quantum allocates the first available IP from that subnet to the port. If you specify both a subnet ID and an IP address, Quantum tries to allocate the specified address to the port. Host routes for the port, in addition to the host routes defined for the subnets that the port is associated with. This operation requires a request body. This operation returns a response body. POST /v2.0/ports.json HTTP/1.1 Content-Length: 158 content-type: application/json accept: application/json

This operation requires a request body. This operation returns a response body. This operation enables you to create several ports in a single request. Specify a list of ports in the request body. xx The &APIv2; always guarantees the atomic completion of the bulk operation.

Verb URI Description &PUT; /ports/port-id Updates the specified port. Normal Response Code: 200 Error Response Codes: Bad Request (400), Unauthorized (401), Forbidden (403), Not Found (404), Conflict (409), Unprocessable Entity (422) You can use this operation to update information for a port, such as its symbolic name and associated IPs. When you update IPs for a port, the previously associated IPs are removed, returned to the respective subnets allocation pools, and replaced by the IPs specified in the body for the update request. Therefore, this operation replaces the fixed_ip attribute when it is specified in the request body. If the new IP addresses are not valid, for example, they are already in use, the operation fails and the existing IP addresses are not removed from the port. This operation requires a request body. This operation returns a response body. PUT /v2.0/ports/1d8591f4-7b62-428e-857d-e82a15e5a7f1.json HTTP/1.1 Content-Length: 63 content-type: application/json accept: application/json { "port": { "device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63" } } Status: 200 Content-Type: application/json; Content-Length: 410 { "port": { "admin_state_up": true, "device_id": "37b4f622-5e17-4dca-bf67-7338c5b7dd63", "fixed_ips": [ { "ip_address": "192.168.111.4", "subnet_id": "22b44fc2-4ffb-4de4-b0f9-69d58b37ae27" } ], "id": "1d8591f4-7b62-428e-857d-e82a15e5a7f1", "mac_address": "fa:16:3e:70:d2:8c", "name": "port2", "network_id": "6aeaf34a-c482-4bd3-9dc3-7faf36412f12", "status": "ACTIVE", "tenant_id": "cf1a5775e766426cb1968766d0191908" } }

Verb URI Description &DELETE; /ports/port-id Removes the specified port. Normal Response Code: 204 Error Response Codes: Unauthorized (401), Forbidden (403), Not Found (404) This operation removes a port from a Quantum network. If IP addresses are associated with the port, they are returned to the respective subnets allocation pools. This operation does not require a request body. This operation does not return a response body. DELETE /v2.0/ports/ebe69f1e-bc26-4db5-bed0-c0afb4afe3db.json accept: application/json status: 204