Difference between revisions of "MelangeAPIBase"

Revision as of 14:07, 6 July 2011

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.

• All GET /resources accepts 'limit' and 'marker' params. If these params are not passed default limit is applied.
• Any request can specify format of data it can accept via 'Accept' HTTP header or add a suffix(.json or .xml) to url.
• The url suffix will override the format specified in 'Accept' header.
• If POST or PUT on a resource doesn't send mandatory params, API returns 400 Bad request response.

List all versions

Method  : GET URL  : / Params  : None Description  : Lists all versions of the API(Currently, Only v0.1 will be listed) Response Code : Success - 200 OK

All the urls below are prefixed by "/v0.1".

Public IP Blocks

Method  : GET URL  : /ipam/public_ip_blocks Params  : None Description  : Lists all public ip blocks Response Code : Success - 200 OK

Method  : POST URL  : /ipam/public_ip_blocks Params  : 'cidr': IpV4 or IpV6 cidr [Mandatory]

• 'network_id' : Can be a uuid, any string accepted

Description  : Create a public ip block Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/public_ip_blocks/:(id) Params  : None Description  : Delete a public ip block by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When IpBlock doesn't exist]

Method  : GET URL  : /ipam/public_ip_blocks/:(id) Params  : None Description  : Get details of a public ip block by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When IpBlock doesn't exist]

Private IP Blocks

Method  : GET URL  : /ipam/tenants/{tenant_id}/private_ip_blocks Params  : None Description  : Lists all private ip blocks of a tenant Response Code : Success - 200 OK

Method  : POST URL  : /ipam/tenants/{tenant_id}/private_ip_blocks Params  : 'cidr': IpV4 or IpV6 cidr [Mandatory]

• 'network_id' : Can be a uuid, any string accepted

Description  : Create a private ip block for given tenant Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/tenants/{tenant_id}/private_ip_blocks/:(id) Params  : None Description  : Delete a tenant's private ip block by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When IpBlock doesn't exist]

Method  : GET URL  : /ipam/tenants/{tenant_id}/private_ip_blocks/:(id) Params  : None Description  : Get details of a tenant's private ip block by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When IpBlock doesn't exist]

IpAddress for Public IP Blocks (Accessible to admins only)

Get IpAddress Details for Public IP Block: Method  : GET URL  : /ipam/public_ip_blocks/{ip_block_id}/ip_addresses/{address:.+?} Params  : None Description  : Finds and returns details of IpAddress for given 'address' which belongs to the Ipblock with id="ip_block_id", type="public" and tenant_id=None. Response Code : Success - 200 OK

• Error - 404 Not Found ( When IpBlock for given ip_block_id is not found, or IpAddress for given address is not found)

Get all IpAddresses for Public IP Block Method  : GET URL  : /ipam/public_ip_blocks/{ip_block_id}/ip_addresses Params  : None Description  : Finds and returns all the IpAddresses which belongs to the Ipblock with id="ip_block_id", type="public" and tenant_id=None Response Code : Success - 200 OK

• Error - 404 Not Found ( When IpBlock for given ip_block_id is not found)

Allocate a new IpAddress from a Public IP Block Method  : POST URL  : /ipam/public_ip_blocks/{ip_block_id}/ip_addresses Params  : [port_id, address](optional) Description  : Allocates an IpAddress from Ipblock with id="ip_block_id", type="public" and tenant_id=None. If address is passed in params, IpAddress with that address is tried to be allocated.

• If port_id is passed, that is set on allocated IpAddress.

Response Code : Success - 201 Created

• Error - 404 Not Found ( When IpBlock for given ip_block_id is not found)
  • 422 Unprocessable Entity ( If any new ip_address can not be allocated from IpBlock )

Delete an IpAddress from a Public IP Block Method  : DELETE URL  : /ipam/public_ip_blocks/{ip_block_id}/ip_addresses/{address:.+?} Params  : None Description  : Deletes IpAddress with address="address" belonging to IpBlock with id="ip_block_id", type="public", tenant_id=None Response Code : Success - 200 OK

• Error - 404 Not Found ( When ip_block for given ip_block_id is not found)

Restore a deallocated IpAddress from Public IP Block Method  : PUT URL  : /ipam/public_ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/restore Params  : None Description  : Finds IpAddress with address="address" belonging to IpBlock with id="ip_block_id", type="public", tenant_id=None and restores it if was deallocated earlier. Response Code : Success - 200 OK

• Error - 404 Not Found (When IpBlock for given ip_block_id is not found or IpAddress for given address is not found)

IpAddress For Tenant's Private IP Block

Get IpAddress Details for Tenant's Private IP Block: Method  : GET URL  : /ipam/tenants/{tenant_id}/private_ip_blocks/{ip_block_id}/ip_addresses/{address:.+?} Params  : None Description  : Finds and returns details of IpAddress for given 'address' which belongs to the Ipblock with id="ip_block_id", type="private" and tenant_id="tenant_id". Response Code : Success - 200 OK

• Error - 404 Not Found ( When either IpBlock for given id and tenant_id is not found, or IpAddress for given address is not found)

Get all IpAddresses for Tenant's Private IP Block Method  : GET URL  : /ipam/tenants/{tenant_id}/private_ip_blocks/{ip_block_id}/ip_addresses Params  : None Description  : Finds and returns all the IpAddresses which belongs to the Ipblock with id="ip_block_id", type="private" and tenant_id="tenant_id". Response Code : Success - 200 OK

• Error - 404 Not Found ( When IpBlock for given id and tenant_id is not found)

Allocate a new IpAddress from Tenant's Private IP Block Method  : POST URL  : /ipam/tenants/{tenant_id}/private_ip_blocks/{ip_block_id}/ip_addresses Params  : [port_id, address](optional) Description  : Allocates an IpAddress from Ipblock with id="ip_block_id", type="private" and tenant_id="tenant_id". If address is passed in params, IpAddress with that address is tried to be allocated.

• If port_id is passed, that is set on allocated IpAddress

Response Code : Success - 201 Created

• Error - 404 Not Found ( When IpBlock for given id and tenant_id is not found)
  • 422 Unprocessable Entity ( If any new ip_address can not be allocated from IpBlock )

Delete an IpAddress from Tenant's Private IP Block Method  : DELETE URL  : /ipam/tenants/{tenant_id}/private_ip_blocks/{ip_block_id}/ip_addresses/{address:.+?} Params  : None Description  : Deletes IpAddress with address="address" belonging to IpBlock with id="ip_block_id", type="private", tenant_id="tenant_id" Response Code : Success - 200 OK

• Error - 404 Not Found ( When ip_block for given id and tenant_id is not found)

Restore a deallocated IpAddress from Tenant's Private IP Block Method  : PUT URL  : /ipam/tenants/{tenant_id}/private_ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/restore Params  : None Description  : Finds IpAddress with address="address" belonging to IpBlock with id="ip_block_id", type="private", tenant_id="tenant_id" and restores it if was deallocated earlier Response Code : Success - 200 OK

• Error - 404 Not Found ( When IpBlock for given id and tenant_id is not found or IpAddress for given address is not found)

Natting

Add Inside Global IPs to a local IP Method  : POST URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_globals Params  : {'ip_addresses':'[ { "ip_block_id" : "some_global_ip_block_id", "ip_address" : "some_global_ip_address" } ... {} } Description  : Finds local IpAddress from given ip_block_id and address and adds IpAddresses passed in params as its inside global. Response Code : Success - 200 OK

Add Inside Local IPs to a global IP Method  : POST URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_locals Params  : {'ip_addresses':'[ { "ip_block_id" : "some_local_ip_block_id", "ip_address" : "some_local_ip_address" } ... {} } Description  : Finds global IpAddress from given ip_block_id and address and adds IpAddresses passed in params as its inside local. Response Code : Success - 200 OK

List all inside globals for a local ip_address Method  : GET URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_globals Params  : None Description  : Finds the local ip_address from given ip_block_id and address, and return all its inside global ip_addresses. Response Code : Success - 200 OK

List all inside locals for a global ip_address Method  : GET URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_locals Params  : None Description  : Finds the global ip_address from given ip_block_id and address, and return all its inside local ip_addresses. Response Code : Success - 200 OK

Delete all inside locals for a global ip_address Method  : DELETE URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_locals Params  : None Description  : Finds the global ip_address from given ip_block_id and address, and remove all its inside local ip_addresses. Response Code : Success - 200 OK

Delete a specific inside local for a global ip_address Method  : DELETE URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_locals/{inside_locals_address:.+?} Params  : None Description  : Finds the global ip_address from given ip_block_id and address, and remove its inside local ip_address whose address is same as given inside_locals_address. Response Code : Success - 200 OK

Delete all inside globals for an inside ip_address Method  : DELETE URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_globals Params  : None Description  : Finds the inside ip_address from given ip_block_id and address, and remove all its inside global ip_addresses. Response Code : Success - 200 OK

Delete a specific inside global for an inside ip_address Method  : DELETE URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address:.+?}/inside_globals/{inside_globals_address:.+?} Params  : None Description  : Finds the inside ip_address from given ip_block_id and address, and remove its inside global ip_address whose address is same as given inside_global_address. Response Code : Success - 200 OK

Global Policies

Method  : GET URL  : /ipam/policies Params  : None Description  : Lists all global policies Response Code : Success - 200 OK

Method  : POST URL  : /ipam/policies Params  : 'name': string [Mandatory]

• 'description' : string

Description  : Create a global policy Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/policies/:(id) Params  : None Description  : Delete a global policy by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy doesn't exist]

Method  : GET URL  : /ipam/policies/:(id) Params  : None Description  : Get details of a global policy by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy doesn't exist]

Method  : PUT URL  : /ipam/policies/:(id) Params  : 'name', 'description' Description  : Update details of a global policy by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy doesn't exist]

Global Policy Unusable Ip Ranges

Method  : GET URL  : /ipam/policies/{policy_id}/unusable_ip_ranges Params  : None Description  : Lists all unusable ip ranges of a global policy Response Code : Success - 200 OK

Method  : POST URL  : /ipam/policies/{policy_id}/unusable_ip_ranges Params  : 'offset': integer [Mandatory, Can be +ve or -ve integer]

• 'length' : integer [Mandatory, Should be +ve integer]

Description  : Create a unusable ip range in global policy Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : None Description  : Delete a global policy's unusable ip range by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Method  : GET URL  : /ipam/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : None Description  : Get details of a global policy's unusable ip range by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Method  : PUT URL  : /ipam/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : 'offset', 'length' Description  : Update details of a global policy's unusable ip range by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Global Policy Unusable Ip Octets

Method  : GET URL  : /ipam/policies/{policy_id}/unusable_ip_octets Params  : None Description  : Lists all unusable ip octets of a global policy Response Code : Success - 200 OK

Method  : POST URL  : /ipam/policies/{policy_id}/unusable_ip_octets Params  : 'octet': integer [Mandatory, Should be 0-255] Description  : Create a unusable ip octet in global policy Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/policies/{policy_id}/unusable_ip_octets/:(id) Params  : None Description  : Delete a global policy's unusable ip octet by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Method  : GET URL  : /ipam/policies/{policy_id}/unusable_ip_octets/:(id) Params  : None Description  : Get details of a global policy's unusable ip octet by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Method  : PUT URL  : /ipam/policies/{policy_id}/unusable_ip_octets/:(id) Params  : 'octet' Description  : Update details of a global policy's unusable ip octet by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Tenant Policies

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies Params  : None Description  : Lists all tenant's policies Response Code : Success - 200 OK

Method  : POST URL  : /ipam/tenants/{tenant_id}/policies Params  : 'name': string [Mandatory]

• 'description' : string

Description  : Create a tenant's policy Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/tenants/{tenant_id}/policies/:(id) Params  : None Description  : Delete a tenant's policy by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy doesn't exist]

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/:(id) Params  : None Description  : Get details of a tenant's policy by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy doesn't exist]

Method  : PUT URL  : /ipam/tenants/{tenant_id}/policies/:(id) Params  : 'name', 'description' Description  : Update details of a tenant's policy by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy doesn't exist]

Tenant Policy Unusable Ip Ranges

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges Params  : None Description  : Lists all unusable ip ranges of a tenant's policy Response Code : Success - 200 OK

Method  : POST URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges Params  : 'offset': integer [Mandatory, Can be +ve or -ve integer]

• 'length' : integer [Mandatory, Should be +ve integer]

Description  : Create a unusable ip range in tenant's policy Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : None Description  : Delete a tenant's policy's unusable ip range by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : None Description  : Get details of a tenant's policy's unusable ip range by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Method  : PUT URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : 'offset', 'length' Description  : Update details of a tenant's policy's unusable ip range by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Tenant Policy Unusable Ip Octets

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets Params  : None Description  : Lists all unusable ip octets of a tenant's policy Response Code : Success - 200 OK

Method  : POST URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets Params  : 'octet': integer [Mandatory, Should be 0-255] Description  : Create a unusable ip octet in tenant's policy Response Code : Success - 201 Created

Method  : DELETE URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Params  : None Description  : Delete a tenant's policy's unusable ip octet by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Params  : None Description  : Get details of a tenant's policy's unusable ip octet by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Method  : PUT URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Params  : 'octet' Description  : Update details of a tenant's policy's unusable ip octet by given id Response Code : Success - 200 OK

• Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Extensions

The API works similar to Nova extensions.

To Be Done:

• Add 'previous' and 'next' links in list all resources (#56) * Add network info like gateway, dns etc. during block creation (#63) * Add API to allocate ip address in a given network (#64)