Jump to: navigation, search

MelangeAPIBase

Melange API Specification

Contents

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

JSON Response:


{
 "versions": 
                 [
                   {"status": "CURRENT", "name": "v0.1", "links":  [ {"href": "http://localhost:9898/v0.1", "rel": "self"}]
                   }
                 ]
}


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".

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': Is a uuid, has to be an existing policy

'dns1': Primary dns server ip address, defaults to dns configured in melange

'dns2': Secondary dns server ip address, defaults to dns configured in melange

'gateway': any valid ip address, defaults to second ip address of the block-~+~

Response Codes:

~+~-Normal Response code: 201

Error - 400 Bad Request [When mandatory fields are not present or field validations fail]-~+~


Create tenant's subnet


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

Params:

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

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

'policy_id' : Is a uuid, has to be an existing policy

'tenant_id' : Can be a uuid, any string accepted, defaults to parent block's tenant_id-~+~

Response Codes:

~+~-Normal Response code: 201

Error - 404 Not Found [When IpBlock for given ip_block_id and tenant_id doesn't exist]

Error - 400 Bad Request [When mandatory fields are not present or field validations fails]-~+~


Update tenant's IP block


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

Params:

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

'policy_id' : Is a uuid, has to be an existing policy-~+~

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for given id and tenant_id doesn't exist]

Error - 400 Bad Request [When field validations fails]-~+~


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 for given id and tenant_id doesn't exist]-~+~

IP Address from Tenant's IP Blocks


List tenant's addresses


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


List tenant's allocated addresses


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

Params:

'used_by_device': uuid of a device, can be any string. If given, IPs allocated to this device will be filtered and returned

Response Codes:

Normal Response code: 200


List Cloud Providers allocated addresses


Verb URI
GET /ipam/allocated_ip_addresses

Params:

'used_by_device': uuid of a device, can be any string. If given, IPs allocated to this device will be filtered and returned

Response Codes:

Normal Response code: 200


Get address details


Verb URI
GET /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address}

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


Verb URI
POST /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.

'interface_id' : Can be a uuid, any string accepted. Is an id pointing to the interface on which the ip will be configured

'tenant_id' : The 'lessee' tenant (the tenant actually using the ip, as opposed to the tenant owning the block). Defaults to the tenant owning the block.

'used_by_device' : Can be a uuid, any string accepted. Is an id pointing to the instance(or any other device) on which the ip will be used.

'mac_address' : any valid mac_address, applicable only for generating ipv6 addresses, Mandatory for ipv6 blocks.-~+~

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]

Error - 400 Bad Request [When mandatory fields are not present or fields fail validations]-~+~


Deallocate tenant's address


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


Verb URI
PUT /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address}/restore

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)-~+~

Static Routes


List all Static Routes for an IpBlock


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

Params:

None

Response Codes:

Normal Response code: 200


Get details of a static route


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

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for given ip_block_id and tenant_id does not exists or IpRoute for given id does not exists]-~+~


Create a Static Route for an IpBlock


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

Params:

~+~-'destination' : [Mandatory] IpAddress or Cidr of the destination host or network.

'netmask : netmask of the destination network, if applicable.

'gateway' : [Mandatory] IpAddress of the gateway.-~+~

Response Codes:

~+~-Normal Response code: 201

Error - 404 Not Found [When IpBlock for given ip_block_id and tenant_id does not exists]

Error - 400 Bad Request [When required parameters are not present or field validation fails]-~+~


Update a static route


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

Params:

~+~-'destination' : IpAddress or Cidr of the destination host or network.

'netmask : netmask of the destination network, if applicable.

'gateway' : IpAddress of the gateway.-~+~

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for given ip_block_id and tenant_id does not exists or Static Route for given id does not exists]

Error - 400 Bad Request [When field validation fails]-~+~


Delete a static route


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

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When IpBlock for given ip_block_id and tenant_id does not exists or Static Route for given id does not exists]-~+~

IP allocations in a Network


Allocate address from tenant's network


Verb URI
POST /ipam/tenants/{tenant_id}/networks/{network_id}/interfaces/{interface_id}/ip_allocations

Params:

~+~-'addresses' : These addresses(can be array of ipv4 and/or ipv6 addresses) are used for allocation. If not provided, next available address will be allocated from one IPv4 and one IPv6 block.

'mac_address' : This will used while allocation IPv6 address. Mandatory if network has IPv6 block.

'tenant_id' : The 'lessee' tenant (the tenant actually using the ip, as opposed to the tenant owning the block). Defaults to the tenant owning the block from which IPs are allocated.

'used_by_device' : Can be a uuid, any string accepted. Is an id pointing to the instance(or any other device) on which the ip will be used.-~+~

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]-~+~

Error - 400 Bad Request [When required parameters are not present or field validation fails]-~+~


List allocated IpAddresses from a tenant's network


Verb URI
GET /ipam/tenants/{tenant_id}/networks/{network_id}/interfaces/{interface_id}/ip_allocations

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


Verb URI
DELETE /ipam/tenants/{tenant_id}/networks/{network_id}/interfaces/{interface_id}/ip_allocations

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


Verb URI
GET /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_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


Verb URI
GET /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_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


Verb URI
POST /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" }, ..., {....} }

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


Verb URI
POST /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_globals

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


Verb URI
DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_globals/{inside_globals_address}

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


Verb URI
DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_locals/{inside_locals_address}

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


Verb URI
DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_locals/{address}

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


Verb URI
DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_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]-~+~

IP Policy

Policy


List all Tenant's IP Policies


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

Params:

None

Response Codes:

Normal Response code: 200


Get details of a Tenant's IP Policy


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

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When Policy for given id and tenant_id does not exists]-~+~


Create an IP Policy for a tenant


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

Params:

~+~-'name' : [Mandatory] Name of the policy.

'description' : Small description about the policy.-~+~

Response Codes:

~+~-Normal Response code: 201

Error - 400 Bad Request [When required parameters are not present or field validation fails]-~+~


Update an IP Policy for a tenant


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

Params:

~+~-'name' : Name of the policy.

'description' : Small description about the policy.-~+~

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When Policy for given id and tenant_id does not exists]

Error - 400 Bad Request [When required parameters are not present or field validation fails]-~+~


Delete an IP Policy for a tenant


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

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When Policy for given id and tenant_id does not exists]-~+~

Unusable IP Ranges


List all unusable ip ranges of a tenant's policy


Verb URI
GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges

Params:

None

Response Codes:

~+~-Normal Response code: 200

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


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


Verb URI
GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When Policy or IP Range doesn't exist]-~+~


Create a unusable ip range in tenant's policy


Verb URI
POST /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 Codes:

~+~-Normal Response code: 201

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


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


Verb URI
PUT /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id)

Params:

~+~-'offset': integer [Can be +ve or -ve integer]

'length' : integer [Should be +ve integer]-~+~

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When Policy or IP range doesn't exist]-~+~


Delete a tenant's policy's unusable ip range


Verb URI
DELETE /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id)

Params:

None

Response Codes:

~+~-Normal Response code: 200

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


Verb URI
GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets

Params:

None

Response Codes:

~+~-Normal Response code: 200

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


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


Verb URI
GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id)

Params:

None

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When Policy or IP octet doesn't exist]-~+~


Create a unusable ip octet in tenant's policy


Verb URI
POST /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets

Params:

'octet': integer [Mandatory, Should be 0-255]

Response Codes:

~+~-Normal Response code: 201

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


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


Verb URI
PUT /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id)

Params:

'octet': integer [Should be 0-255]

Response Codes:

~+~-Normal Response code: 200

Error - 404 Not Found [When Policy or IP octet doesn't exist]-~+~


Delete a tenant's policy's unusable ip octet


Verb URI
DELETE /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id)

Params:

None

Response Codes:

~+~-Normal Response code: 200

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