Revision as of 11:29, 7 September 2011

Melange API Specification

<<TableOfContents()>>

General Information

The Melange API is implemented using a RESTful web service interface.

• All GET /resources accepts 'limit' and 'marker' params. If these params are not passed default limit is applied.
• If POST or PUT on a resource doesn't send mandatory params, API returns '400 Bad Request' response.

Request/Response Types

• The Melange API supports both the JSON and XML data serialization formats.
• The request format is specified using the Content-Type header and is required for operations that have a request body.
• The response format can be specified in requests using either the Accept header or adding an .xml or .json extension to the request URI.
• If no response format is specified, JSON is the default.
• If conflicting formats are specified using both an Accept header and a query extension, the query extension takes precedence.

Versions

List versions

Params:

None

Response Codes:

Normal Response code: 200

Extensions

The Melange API is extensible. The API Extensions allow introducing new features in the API without requiring a version change and allows vendor specific niche functionality. The API extensions work similar to nova extensions.

List extensions

Params:

None

Response Codes:

Normal Response code: 200

List extension details

Params:

None

Response Codes:

Normal Response code: 200

NOTE:

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

IP Blocks

List Tenant's blocks

Params:

type ('public' or 'private')

Response Codes:

Normal Response code: 200

List Tenant's subnets

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

Get details of tenant's IP block

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

Create tenant's IP block

Params:

~+~-'type': 'public' or 'private' [Mandatory]

'cidr': IPV4 or IPV6 cidr [Mandatory]

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

'policy_id' : Can be a uuid, any string accepted-~+~

Response Codes:

Normal Response code: 201

Create tenant's subnet

Params:

~+~-'type': 'cidr': IpV4 or IpV6 cidr [Mandatory]

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

'policy_id' : Can be a uuid, any string accepted-~+~

Response Codes:

~+~-Normal Response code: 201

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

Update tenant's IP block

Params:

~+~-'type': 'network_id' : Can be a uuid, any string accepted

'policy_id' : Can be a uuid, any string accepted-~+~

Response Codes:

~+~-Normal Response code: 200

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

Delete tenant's IP block

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

IP Address from Tenant's IP Blocks

List tenant's addresses

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found (When IpBlock for given ip_block_id and tenant_id is not found)-~+~

Get address details

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

Allocate tenant's address

Params:

~+~-'address' : This address is used for allocation. If this is not provided, next available address will be allocated.

'interface_id' : Can be a uuid, any string accepted-~+~

Response Codes:

~+~-Normal Response code: 201

Error - 404 Not Found [When IpBlock for given ip_block_id is not found] Error - 422 Unprocessable Entity [If any new ip_address can not be allocated from IpBlock] Error - 409 Conflict [If the given address is already allocated]-~+~

Deallocate tenant's address

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

Restore tenant's address

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

IP allocations in a Network

These API create an IPv4 and IPv6 address for given interface.

Allocate address from tenant's network

Params:

'address' : This address is used for allocation. If this is not provided, next available address will be allocated.

Response Codes:

~+~-Normal Response code: 201

Error - 422 Unprocessable Entity [If ip address can not be allocated from Network]

Error - 404 Not Found [When network for a given network_id and tenant_id is not found]

Error - 409 Conflict [If the given address is already allocated]-~+~

List allocated IpAddresses from a tenant's network

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When network for a given network_id and tenant_id is not found]-~+~

Deallocate all IpAddresses from a tenant's network

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When network for a given network_id and tenant_id is not found]-~+~

NAT'ing

Tracking NAT information is designed to assist in the implementation and tracking of floating IPs.

List globals

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for ip block ID or IP Address by given address is not found]-~+~

List locals

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IP Block for ip_block_id or IpAddress by given address is not found]-~+~

Assign globals

Params:

{'ip_addresses':'[ { "ip_block_id" : "some_global_ip_block_id", "ip_address" : "some_global_ip_address" } ... {} }

Response Codes:

~+~-Normal Response code: 200

Error - 400 Bad Request [When the values of ip_block_id and ip_address are missing in the params]-~+~

Assign locals

Params:

{'ip_addresses':'[ { "ip_block_id" : "some_local_ip_block_id", "ip_address" : "some_local_ip_address" } ... {} }

Response Codes:

~+~-Normal Response code: 200

Error - 400 Bad Request [When the values of ip_block_id and ip_address are missing in the params]-~+~

Remove global

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for ip_block_id or IpAddress by given address is not found]-~+~

Remove local

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for ip_block_id or IpAddress by given address is not found]-~+~

Remove all globals

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for ip_block_id or IpAddress by given address is not found]-~+~

Remove all locals

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for ip_block_id or IpAddress by given address is not found]-~+~

Tenant Policies

Tenant Policy Unusable Ip Ranges

List all unusable ip ranges of a tenant's policy

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges Params  : None Response Code : Success - 200 OK

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

Get details of a tenant's policy's unusable ip range

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : None Response Code : Success - 200 OK Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Create a unusable ip range in tenant's policy

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] Response Code : Success - 201 Created Error - 404 Not Found [When Policy doesn't exist]

Update details of a tenant's policy's unusable ip range

Method  : PUT URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : 'offset', 'length' Response Code : Success - 200 OK Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Delete a tenant's policy's unusable ip range

Method  : DELETE URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Params  : None Response Code : Success - 200 OK Error - 404 Not Found [When Policy or Ip Range doesn't exist]

Tenant Policy Unusable Ip Octets

List all unusable ip octets of a tenant's policy

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets Params  : None Response Code : Success - 200 OK Error - 404 Not Found [When Policy doesn't exist]

Get details of a tenant's policy's unusable ip octet

Method  : GET URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Params  : None Response Code : Success - 200 OK Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Create a unusable ip octet in tenant's policy

Method  : POST URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets Params  : 'octet': integer [Mandatory, Should be 0-255] Response Code : Success - 201 Created Error - 404 Not Found [When Policy doesn't exist]

Update details of a tenant's policy's unusable ip octet.

Method  : PUT URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Params  : 'octet' Response Code : Success - 200 OK Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

Delete a tenant's policy's unusable ip octet

Method  : DELETE URL  : /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Params  : None Response Code : Success - 200 OK Error - 404 Not Found [When Policy or Ip Octet doesn't exist]

To Be Done:

• Add 'self' and 'bookmark' links in resource details.
• Versions atom feed
• API to list all IPs by an instance_id