Jump to: navigation, search

MelangeAPIBase

Revision as of 02:52, 28 July 2011 by TroyToman (talk)

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


Verb URI
GET /

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


Verb URI
GET /extensions

Params:

None

Response Codes:

Normal Response code: 200


List extension details


Verb URI
GET /extensions/alias

Params:

None

Response Codes:

Normal Response code: 200

NOTE:

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

Global IP Blocks


List IP blocks


Verb URI
GET /ipam/ip_blocks

Params:

type ('public' or 'private')

Response Codes:

Normal Response code: 200


List subnets


Verb URI
GET /ipam/ip_blocks/{ip_block_id}/subnets

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error response code(s): #404-Not Found - when block does not exist -~+~


Get IP block details


Verb URI
GET /ipam/ip_blocks/:(id)

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error response code(s): #404-Not Found - when block does not exist -~+~


Create IP block


Verb URI
POST /ipam/ip_blocks

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 subnet


Verb URI
POST /ipam/ip_blocks/{ip_block_id}/subnets

Params:

~+~-'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 block


Verb URI
PUT /ipam/ip_blocks/:(id)

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: 201

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


Delete block


Verb URI
DELETE /ipam/ip_blocks/:(id)

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

Tenant's IP Blocks


List Tenant's blocks


Verb URI
GET /ipam/tenants/{tenant_id}/ip_blocks

Params:

type ('public' or 'private')

Response Codes:

Normal Response code: 200


List Tenant's subnets


Verb URI
GET /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/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


Verb URI
GET /ipam/tenants/{tenant_id}/ip_blocks/:(id)

Params:

None

Response Codes:

~+~-Normal Response code: 200

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


Create tenant's IP block


Verb URI
POST /ipam/tenants/{tenant_id}/ip_blocks

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


Verb URI
POST /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/subnets

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


Verb URI
PUT /ipam/tenants/{tenant_id}/ip_blocks/:(id)

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


Verb URI
DELETE /ipam/tenants/{tenant_id}/ip_blocks/:(id)

Params:

None

Response Codes:

~+~-Normal Response code: 200

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

IP Address from Global IP Blocks

  • List all ip addresses in the ip block.
       Method        : GET
       URL           : /ipam/ip_blocks/{ip_block_id}/ip_addresses
       Params        : None
       Response Code : Success - 200 OK
                       Error   - 404 Not Found (When IpBlock for given ip_block_id is not found)
  • Get details of an ip address.
       Method        : GET
       URL           : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}
       Params        : 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]
       Method        : POST
       URL           : /ipam/ip_blocks/{ip_block_id}/ip_addresses
       Params        : 'address' : This address is used for allocation. If this is not provided, next available address will be allocated.
                       'port_id' : Can be a uuid, any string accepted
       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]
                                 409 Conflict [If the given address is already allocated]
       Method        : DELETE
       URL           : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}
       Params        : 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]
  • Restore a deallocated address.
       Method        : PUT
       URL           : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/restore
       Params        : 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]

IP Address from Tenant's IP Blocks

  • Get details of an ip address in a tenant's ip block.
       Method        : GET
       URL           : /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address}
       Params        : None
       Response Code : Success - 200 OK
                       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]
  • List all ip addresses in a tenant's ip block.
       Method        : GET
       URL           : /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses
       Params        : None
       Response Code : Success - 200 OK
                       Error   - 404 Not Found [When IpBlock for given ip_block_id and tenant_id is not found]
  • Allocate an IpAddress from a tenant's block.
       Method        : POST
       URL           : /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses
       Params        : 'address' : This address is used for allocation. If this is not provided, next available address will be allocated.
                       'port_id' : Can be a uuid, any string accepted
       Response Code : Success - 201 Created
                       Error   - 404 Not Found [When IpBlock for given ip_block_id and tenant_id is not found]
                                 422 Unprocessable Entity [If any new ip_address can not be allocated from IpBlock]
                                 409 Conflict [If the given address is already allocated]
  • Deallocate an IpAddress from a tenant's block.
       Method        : DELETE
       URL           : /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address}
       Params        : None
       Response Code : Success - 200 OK
                       Error   - 404 Not Found [When ip_block for given id and tenant_id is not found]
  • Restore a deallocated address from a tenant's block.
       Method        : PUT
       URL           : /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address}/restore
       Params        : None
       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]

IP allocations in a Network

These API create an ipv4 and ipv6 address for given interface(port).

  • Allocate an IpAddress from a global network.
       Method        : POST
       URL           : /ipam/networks/{network_id}/ports/{port_id}/ip_allocations
       Params        : 'address' : This address is used for allocation. If this is not provided, next available address will be allocated.
       Response Code : Success - 201 Created
                       Error   - 422 Unprocessable Entity [If ip address can not be allocated from Network]
                                 409 Conflict [If the given address is already allocated]
  • Allocate an IpAddress from a tenant's network.
       Method        : POST
       URL           : /ipam/tenants/{tenant_id}/networks/{network_id}/ports/{port_id}/ip_allocations
       Params        : 'address' : This address is used for allocation. If this is not provided, next available address will be allocated.
       Response Code : Success - 201 Created
                       Error   - 422 Unprocessable Entity [If ip address can not be allocated from tenant's Network]
                                 409 Conflict [If the given address is already allocated]

NAT'ing

  • List all outside globals for a local ip_address

Method  : GET URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_globals Params  : None Description  : Return the outside global ip addresses for the local ip address of the ip_block. Response Code : Success - 200 OK Error - 404 Not Found [When IpBlock for ip block ID or IP Address by given address is not found]

  • 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  : Return the inside local IP addresses for the global IP address of the IP block. Response Code : Success - 200 OK Error - 404 Not Found [When IP Block for ip_block_id or IpAddress by given address is not found]

  • 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 creates IpAddresses passed in params as its inside global. Response Code : Success - 200 OK Error - 400 Bad Request [When the values of ip_block_id and ip_address are missing in the params]

  • 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 Error - 400 Bad Request [When the values of ip_block_id and ip_address are missing in the params]

  • Delete a specific inside global for a local ip_address

Method  : DELETE URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/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 address. Response Code : Success - 200 OK Error - 404 Not Found [When IpBlock for ip_block_id or IpAddress by given address is not found]

  • Delete a specific inside local for a global ip_address

Method  : DELETE URL  : /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/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 address. Response Code : Success - 200 OK Error - 404 Not Found [When IpBlock for ip_block_id or IpAddress by given address is not found]

  • Delete all inside globals for a local 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

       								Error   - 404 Not Found [When IpBlock for ip_block_id or IpAddress by given address is not found]
  • 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 Error - 404 Not Found [When IpBlock for ip_block_id or IpAddress for global ip_address are not found]

Global Policies

  • Lists all global policies

Method  : GET URL  : /ipam/policies Params  : None Response Code : Success - 200 OK

  • Get details of a global policy

Method  : GET URL  : /ipam/policies/:(id) Params  : None Response Code : Success - 200 OK Error - 404 Not Found [When Policy doesn't exist]

  • Create a global policy

Method  : POST URL  : /ipam/policies Params  : 'name': string [Mandatory] 'description' : string Response Code : Success - 201 Created Error - 422 UnProcessable Entity [When name is None]

  • Update details of a global policy

Method  : PUT URL  : /ipam/policies/:(id) Params  : 'name', 'description' Response Code : Success - 200 OK Error - 404 Not Found [When Policy doesn't exist]

  • Delete a global policy

Method  : DELETE URL  : /ipam/policies/:(id) Params  : None Response Code : Success - 200 OK Error - 404 Not Found [When Policy doesn't exist]

Global Policy Unusable Ip Ranges

  • List all unusable ip ranges of a global policy

Method  : GET URL  : /ipam/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 global policy's unusable ip range

Method  : GET URL  : /ipam/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 global policy

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

  • Update details of a global policy's unusable ip range

Method  : PUT URL  : /ipam/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 global policy's unusable ip range

Method  : DELETE URL  : /ipam/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]

Global Policy Unusable Ip Octets

  • List all unusable ip octets of a global policy

Method  : GET URL  : /ipam/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 global policy's unusable ip octet

Method  : GET URL  : /ipam/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 global policy

Method  : POST URL  : /ipam/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]

  • Delete a global policy's unusable ip octet

Method  : DELETE URL  : /ipam/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]

  • Update details of a global policy's unusable ip octet

Method  : PUT URL  : /ipam/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]

Tenant Policies

  • List all tenant's policies

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

  • Get details of a tenant's policy

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

  • Create a tenant's policy

Method  : POST URL  : /ipam/tenants/{tenant_id}/policies Params  : 'name': string [Mandatory] 'description' : string Response Code : Success - 201 Created

  • Update details of a tenant's policy

Method  : PUT URL  : /ipam/tenants/{tenant_id}/policies/:(id) Params  : 'name', 'description' Response Code : Success - 200 OK Error - 404 Not Found [When Policy doesn't exist]

  • Delete a tenant's policy
 			Method        : DELETE
 			URL           : /ipam/tenants/{tenant_id}/policies/:(id)
 			Params        : None
 			Response Code : Success - 200 OK
 			                Error   - 404 Not Found [When Policy doesn't exist]

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:

  • Authentication and Authorization using keystone identity service.
  • Add 'next' links in paginated list resources.
  • Add 'self' and 'bookmark' links in resource details.
  • Versions atom feed
  • Versioning by mime type