Table of Contents
The Melange API is implemented using a RESTful web service interface.
Verb URI Description GET / Lists all versions of the API
Params:
None
Response Codes:
Normal Response code: 200
JSON Response Example:
{
"versions":
[
{
"status":"CURRENT",
"name":"v0.1",
"links":
[
{ "href":"http://melange/v0.1",
"rel":"self"
}
]
}
]
}
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.
Verb URI Description GET /extensions Lists all extensions of the API
Params:
None
Response Codes:
Normal Response code: 200
Verb URI Description GET /extensions/{alias} Get details of all extensions of the API
Params:
None
Response Codes:
Normal Response code: 200
Verb URI Description GET /ipam/tenants/{tenant_id}/ip_blocks List all ip blocks of a tenant
Params:
Response Codes:
Normal Response code: 200
JSON Response Example:
{
"ip_blocks": [
{
"broadcast": "10.1.1.255",
"cidr": "10.1.1.0/24",
"created_at": "2011-12-01T09:39:35",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.1.1.1",
"id": "14819901-693b-4ea6-8be7-67e79b261b5c",
"netmask": "255.255.255.0",
"network_id": "quantum_net_id2",
"parent_id": null,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"tenant_id": "RAX",
"type": "private",
"updated_at": "2011-12-01T09:39:35"
},
{
"broadcast": "10.1.1.255",
"cidr": "10.1.1.0/24",
"created_at": "2011-12-01T09:42:13",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.1.1.1",
"id": "4ad71669-7225-4e3c-b82c-38533ddaef23",
"netmask": "255.255.255.0",
"network_id": "quantum_net_id3",
"parent_id": null,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"tenant_id": "RAX",
"type": "private",
"updated_at": "2011-12-01T09:42:13"
},
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/subnets List all subnets of a tenant’s ip block
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When IpBlock doesn’t exist]
JSON Response Example:
{
"subnets": [
{
"broadcast": "10.1.1.3",
"cidr": "10.1.1.0/30",
"created_at": "2011-12-01T10:47:57",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.1.1.1",
"id": "5a306fcd-41c9-463b-8c73-c2179cc77c05",
"netmask": "255.255.255.252",
"network_id": "quantum_net_id2",
"parent_id": "14819901-693b-4ea6-8be7-67e79b261b5c",
"policy_id": null,
"tenant_id": "RAX",
"type": "private",
"updated_at": "2011-12-01T10:47:57"
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/ip_blocks/:(id) Get details of a tenant’s ip block
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When IpBlock doesn’t exist]
JSON Response Example:
{
"ip_block": {
"broadcast": "10.1.1.255",
"cidr": "10.1.1.0/24",
"created_at": "2011-12-01T09:46:22",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.1.1.1",
"id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"netmask": "255.255.255.0",
"network_id": "quantum_net_id4",
"parent_id": null,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"tenant_id": "RAX",
"type": "private",
"updated_at": "2011-12-01T09:46:22"
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/ip_blocks Create a new IP block for a tenant
Params:
{
"ip_block": {
"type": "private"
"cidr": "10.0.0.0/24"
"network_id":"new_net",
"policy_id":"policy_id",
"dns1": "8.8.8.8"
"dns2": "8.8.4.4"
"gateway": "10.0.0.2"
}
}
‘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]
JSON Response Example:
{
"ip_block": {
"broadcast": "10.1.1.255",
"cidr": "10.1.1.0/24",
"created_at": "2011-12-01T09:42:13",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.1.1.1",
"id": "4ad71669-7225-4e3c-b82c-38533ddaef23",
"netmask": "255.255.255.0",
"network_id": "quantum_net_id3",
"parent_id": null,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"tenant_id": "RAX",
"type": "private",
"updated_at": "2011-12-01T09:42:13"
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/subnets Create a new subnet in a tenant’s IP block
Params:
{
"ip_block": {
"cidr": "10.0.0.0/28"
"network_id": "new_net",
"policy_id": "policy_id",
"tenant_id": "subnet_tenant_id"
}
}
‘cidr’: IpV4 or IpV6 cidr that is a subnet of the parent 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 the ip_block_id and tenant_id doesn’t exist]
Error - 400 Bad Request [When mandatory fields are not present or field validations fail]
JSON Response Example:
{
"subnet": {
"broadcast": "10.1.1.3",
"cidr": "10.1.1.0/30",
"created_at": "2011-12-01T10:47:57",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.1.1.1",
"id": "5a306fcd-41c9-463b-8c73-c2179cc77c05",
"netmask": "255.255.255.252",
"network_id": "quantum_net_id2",
"parent_id": "14819901-693b-4ea6-8be7-67e79b261b5c",
"policy_id": null,
"tenant_id": "RAX",
"type": "private",
"updated_at": "2011-12-01T10:47:57"
}
}
Verb URI Description PUT /ipam/tenants/{tenant_id}/ip_blocks/:(id) Update details of a tenant’s ip block
Params:
{
"ip_block": {
"type": "private"
"network_id": "new_net",
"policy_id": "policy_id",
}
}
‘type’: (‘public’ or ‘private’)
‘network_id’ : Can be a uuid, any string accepted
‘policy_id’ : Is a uuid, has to be an existing policy
All other properties of an ip block cannot be updated
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]
JSON Response Example:
{
"ip_block": {
"broadcast": "10.1.1.255",
"cidr": "10.1.1.0/24",
"created_at": "2011-12-01T09:46:22",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.1.1.1",
"id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"netmask": "255.255.255.0",
"network_id": "quantum_net_id4",
"parent_id": null,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"tenant_id": "RAX",
"type": "private",
"updated_at": "2011-12-01T09:46:22"
}
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/ip_blocks/:(id) Deletes the tenant’s ip block
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When IpBlock for with this id and tenant_id doesn’t exist]
Verb URI Description GET /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses List all ip addresses in a tenant’s ip block. This will return all allocated and soft deallocated ip addresses
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found (When an ip_address for the ip_block_id and tenant_id is not found)
JSON Response Example:
{
"ip_addresses": [
{
"address": "10.1.1.3",
"created_at": "2011-12-01T10:01:55",
"id": "8ced0b07-45e6-40e2-9073-c84182890875",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:01:55",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
},
{
"address": "10.1.1.6",
"created_at": "2011-12-01T10:02:53",
"id": "94fa249b-0626-49fc-b420-cce13dabed4f",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:02:53",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/allocated_ip_addresses List all allocated ip addresses leased to tenant
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
JSON Response Example:
{
"ip_addresses": [
{
"address": "10.1.1.3",
"created_at": "2011-12-01T10:01:55",
"id": "8ced0b07-45e6-40e2-9073-c84182890875",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:01:55",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
},
{
"address": "10.1.1.6",
"created_at": "2011-12-01T10:02:53",
"id": "94fa249b-0626-49fc-b420-cce13dabed4f",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:02:53",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
}
]
}
Verb URI Description GET /ipam/allocated_ip_addresses List all cloud provider’s 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
JSON Response Example:
{
"ip_addresses": [
{
"address": "10.1.1.3",
"created_at": "2011-12-01T10:01:55",
"id": "8ced0b07-45e6-40e2-9073-c84182890875",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:01:55",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
},
{
"address": "10.1.1.6",
"created_at": "2011-12-01T10:02:53",
"id": "94fa249b-0626-49fc-b420-cce13dabed4f",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:02:53",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address} Get details of an ip address in a tenant’s ip block.
Params:
{address} in the URI is the ipv4 or ipv6 address
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)
JSON Response Example:
{
"ip_address": {
"address": "10.1.1.6",
"created_at": "2011-12-01T10:02:53",
"id": "94fa249b-0626-49fc-b420-cce13dabed4f",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:02:53",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses Allocate an IpAddress from a tenant’s block.
Params:
{
"ip_address": {
"interface_id": "vif_id",
"address": "10.0.0.3",
"tenant_id": "lesse_tenant_id",
"used_by_device": "device_id",
"mac_address": "AB:CD:EF:01:02:03",
}
}
‘interface_id’ : Can be a uuid, any string accepted. Is an id pointing to the interface on which the ip will be configured.
‘address’ : This address is used for allocation. If this is not provided, next available address will be allocated.
‘tenant_id’ : The ‘lessee’ tenant (the tenant 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’ : Optional, can be provided if Melange is not in charge of generating mac addresses.
Response Codes:
Normal Response code: 201
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)
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]
JSON Response Example:
{
"ip_address": {
"address": "10.1.1.6",
"created_at": "2011-12-01T10:02:53",
"id": "94fa249b-0626-49fc-b420-cce13dabed4f",
"interface_id": "interface_id",
"ip_block_id": "af19f87a-d6a9-4ce5-b30f-4cc9878ec292",
"updated_at": "2011-12-01T10:02:53",
"used_by_device": "instance_id",
"used_by_tenant": "lessee_tenant",
"version": 4
}
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address} Deallocate an IpAddress from a tenant’s block. This ip address will be deleted after a certain number of days. Number of days can be configured in melange.conf file.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found (When ip_block for this id and tenant_id is not found)
Verb URI Description PUT /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_addresses/{address}/restore Restores a deallocated (and not deleted) address in a tenant’s block.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found (When IpBlock for this ip_block_id and tenant_id is not found or when address is not found)
Verb URI Description GET /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_routes List all static routes for the ip block.
Params:
None
Response Codes:
Normal Response code: 200
JSON Response Example:
{
"ip_routes": [
{
"created_at": "2011-12-01T10:19:12",
"destination": "192.168.0.0",
"gateway": "10.1.1.1",
"id": "364c555d-4e35-43d4-9807-59535df082a5",
"netmask": "255.255.255.0",
"updated_at": "2011-12-01T10:19:12"
},
{
"created_at": "2011-12-01T10:20:47",
"destination": "192.168.0.0",
"gateway": "10.1.1.1",
"id": "7ebffbd6-3640-4061-b8f1-7878463e651f",
"netmask": "255.255.255.0",
"updated_at": "2011-12-01T10:20:47"
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_routes/:(id) Get details of the static route.
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]
JSON Response Example:
{
"ip_route": {
"created_at": "2011-12-01T10:20:47",
"destination": "192.168.0.0",
"gateway": "10.1.1.1",
"id": "7ebffbd6-3640-4061-b8f1-7878463e651f",
"netmask": "255.255.255.0",
"updated_at": "2011-12-01T10:20:47"
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_routes Create a static route for an ip block.
Params:
{
"ip_route": {
"destination": "10.1.1.1",
"netmask": "255.255.255.0",
"gateway": "10.1.1.0",
}
}
‘destination’ : IpAddress or Cidr of the destination host or network.[Mandatory]
‘netmask : netmask of the destination network, if applicable.
‘gateway’ : IpAddress of the gateway.[Mandatory]
Response Codes:
Normal Response code: 201
Error - 404 Not Found [When IpBlock for the ip_block_id and tenant_id does not exists]
Error - 400 Bad Request [When required parameters are not present or field validations fail]
JSON Response Example:
{
"ip_route": {
"created_at": "2011-12-01T10:20:47",
"destination": "192.168.0.0",
"gateway": "10.1.1.1",
"id": "7ebffbd6-3640-4061-b8f1-7878463e651f",
"netmask": "255.255.255.0",
"updated_at": "2011-12-01T10:20:47"
}
}
Verb URI Description PUT /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_routes/:(id) Update details of a static route.
Params:
{
"ip_route": {
"destination": "10.1.1.1",
"netmask": "255.255.255.0",
"gateway": "10.1.1.0",
}
}
‘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 this id does not exists]
Error - 400 Bad Request [When field validations fail]
JSON Response Example:
{
"ip_route": {
"created_at": "2011-12-01T10:20:47",
"destination": "192.168.0.0",
"gateway": "10.1.1.1",
"id": "7ebffbd6-3640-4061-b8f1-7878463e651f",
"netmask": "255.255.255.0",
"updated_at": "2011-12-01T10:20:47"
}
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/ip_blocks/{ip_block_id}/ip_routes/:(id) delete a static route.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When IpBlock for the ip_block_id and tenant_id does not exists or Static Route for this id does not exists]
Verb URI Description POST /ipam/interfaces/ Creates a vif record, allocates a mac and optionally allocates ip address from a network if specified(requires admin privileges).
Params:
{
"interface": {
"id": "virt_iface",
"device_id": "instance",
"tenant_id": "tnt",
"network": {
"id": "net1",
"addresses": ["10.0.0.2"],
"tenant_id": "network_owner_tenant_id"
}
}
}
‘id’ : virtual interface id generated by caller(eg: nova) for the vnic of a device.
‘tenant_id’ : The ‘lessee’ tenant for whom the interface is being created.
‘device_id’ : 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’ : Optional, can be provided if Melange is not in charge of generating mac addresses.
‘network’ : all network and ip related details.
Response Codes:
Normal Response code: 201
Error - 422 Unprocessable Entity [If ip address cannot 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]
JSON Response Example:
{
"interface": {
"created_at": "2011-12-01T13:18:37",
"device_id": "instance",
"id": "virt_iface",
"ip_addresses": [
{
"address": "10.0.0.2",
"id": "7615ca4a-787d-46b0-8a8c-3a90e3e6cf2c",
"interface_id": "virt_iface",
"ip_block": {
"broadcast": "10.0.0.255",
"cidr": "10.0.0.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.0.0.1",
"id": "9c4c3dfd-c707-45bd-8626-9c369b1b9460",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
],
"mac_address": null,
"tenant_id": "tnt_id",
"updated_at": "2011-12-01T13:18:37"
}
}
Verb URI Description GET /ipam/tenants/{tenant_id}/interfaces/{vif_id} Get interface details along with all ips allocated on it.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When interface is not found]
JSON Response Example:
{
"interface": {
"created_at": "2011-12-01T13:18:37",
"device_id": "instance",
"id": "virt_iface",
"ip_addresses": [
{
"address": "10.0.0.2",
"id": "7615ca4a-787d-46b0-8a8c-3a90e3e6cf2c",
"interface_id": "virt_iface",
"ip_block": {
"broadcast": "10.0.0.255",
"cidr": "10.0.0.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.0.0.1",
"id": "9c4c3dfd-c707-45bd-8626-9c369b1b9460",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
],
"mac_address": null,
"tenant_id": "tnt_id",
"updated_at": "2011-12-01T13:18:37"
}
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/networks/{network_id}/interfaces/{vif_id} delete interface along with all ips allocated on it.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When interface is not found]
Verb URI Description PUT /ipam/instances/{instance_id}/interfaces/ Create interfaces, allocate macs and ips on all networks provided.
Params:
{instance_id} in URI 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.
Params Body Example:
{
"instance": {
"tenant_id": "tnt",
"interfaces": [
{"network": {"id": "public_net1", "tenant_id": "RAX"}, "mac_address": null},
{"network": {"id": "public_net2", "tenant_id": "RAX"}, "mac_address": null},
]
}
}
‘tenant_id’ : The ‘lessee’ tenant for whom the interface is being created.
‘network’ : all network and ip related details.
‘mac_address’ : Optional, can be provided if Melange is not in charge of generating mac addresses.
Response Codes:
Normal Response code: 200
Error - 422 Unprocessable Entity [If ip address cannot 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]
JSON Response Example:
{
"instance":
{
"interfaces" : [
{
"created_at": "2011-12-01T13:18:37",
"device_id": "instance",
"id": "virt_iface",
"ip_addresses": [
{
"address": "10.0.0.2",
"id": "7615ca4a-787d-46b0-8a8c-3a90e3e6cf2c",
"interface_id": "virt_iface",
"ip_block": {
"broadcast": "10.0.0.255",
"cidr": "10.0.0.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.0.0.1",
"id": "9c4c3dfd-c707-45bd-8626-9c369b1b9460",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
],
"mac_address": null,
"tenant_id": "tnt_id",
"updated_at": "2011-12-01T13:18:37"
},
{
"created_at": "2011-12-01T13:18:37",
...
}
]
}
}
Verb URI Description POST /ipam/instances/{instance_id}/interfaces Create an interface with the instance_id and allocate a mac. If a network is provided, allocate an ip as well.
Params:
{instance_id} in URI 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.
Params Body Example:
{
"interface": {
"tenant_id": "tnt",
"mac_address": "null"
"network": {"id": "public_net1", "tenant_id": "RAX"}
}
}
‘tenant_id’ : The ‘lessee’ tenant for whom the interface is being created.
‘mac_address’ : Optional, can be provided if Melange is not in charge of generating mac addresses.
‘network’ : all network and ip related details. The tenant_id in the network property is the network owner
Response Codes:
Normal Response code: 200
Error - 422 Unprocessable Entity [If ip address cannot 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]
JSON Response Example:
{
"interface" : {
"created_at": "2011-12-01T13:18:37",
"device_id": "instance",
"id": "virt_iface",
"ip_addresses": [
{
"address": "10.0.0.2",
"id": "7615ca4a-787d-46b0-8a8c-3a90e3e6cf2c",
"interface_id": "virt_iface",
"ip_block": {
"broadcast": "10.0.0.255",
"cidr": "10.0.0.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.0.0.1",
"id": "9c4c3dfd-c707-45bd-8626-9c369b1b9460",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
],
"mac_address": null,
"tenant_id": "tnt_id",
"updated_at": "2011-12-01T13:18:37"
}
}
Verb URI Description GET /ipam/instances/{instance_id}/interfaces/ Get all interface details of an instance along with all ips allocated on it.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When interface is not found]
JSON Response Example:
{
"instance":
{
"interfaces" : [
{
"created_at": "2011-12-01T13:18:37",
"device_id": "instance",
"id": "virt_iface",
"ip_addresses": [
{
"address": "10.0.0.2",
"id": "7615ca4a-787d-46b0-8a8c-3a90e3e6cf2c",
"interface_id": "virt_iface",
"ip_block": {
"broadcast": "10.0.0.255",
"cidr": "10.0.0.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.0.0.1",
"id": "9c4c3dfd-c707-45bd-8626-9c369b1b9460",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
],
"mac_address": null,
"tenant_id": "tnt_id",
"updated_at": "2011-12-01T13:18:37"
},
{
"created_at": "2011-12-01T13:18:37",
...
}
]
}
}
Verb URI Description GET /ipam/instances/{instance_id}/interfaces/ Get a single interface’s details along with all ips allocated on it.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When interface is not found]
JSON Response Example:
{
"interface" : {
"created_at": "2011-12-01T13:18:37",
"device_id": "instance",
"id": "virt_iface",
"ip_addresses": [
{
"address": "10.0.0.2",
"id": "7615ca4a-787d-46b0-8a8c-3a90e3e6cf2c",
"interface_id": "virt_iface",
"ip_block": {
"broadcast": "10.0.0.255",
"cidr": "10.0.0.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.0.0.1",
"id": "9c4c3dfd-c707-45bd-8626-9c369b1b9460",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
],
"mac_address": null,
"tenant_id": "tnt_id",
"updated_at": "2011-12-01T13:18:37"
}
}
Verb URI Description DELETE /ipam/instances/{instance_id}/interfaces delete all instance interfaces along with all ips allocated on it.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When interface is not found]
Verb URI Description DELETE /ipam/instances/{instance_id}/interfaces/{interface_id} Delete a single interface of the instance and all ips allocated on the interface.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When interface is not found]
Verb URI Description POST /ipam/instances/{instance_id}/interfaces/{interface_id}/ip_addresses Allocate an IPv4 and IPv6 address to the interface based on the network details in the body.
Params:
{instance_id} in URI 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. {interface_id} in URI is the id of an existing interface in Melange
Params Body Example:
{
"network": {
"id": "public_net1",
"tenant_id": "RAX",
"addresses":["10.1.1.1"]}
}
‘network’ : all network and ip related details. The tenant_id in this context is of the network owner.
Response Codes:
Normal Response code: 200
Error - 422 Unprocessable Entity [If ip address cannot 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]
JSON Response Example:
{
"ip_addresses": [
{
"address": "192.168.1.0",
"id": "e9394108-4276-4965-8621-52bfa00464b5",
"interface_id": "123",
"ip_block": {
"broadcast": "192.168.1.255",
"cidr": "192.168.1.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "192.168.1.1",
"id": "d14b95da-261f-4b7e-90a1-0e2902c5f454",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
]
}
Verb URI Description DELETE /ipam/instance/{instance_id}/interfaces/{interface_id}/ip_addresses Delete all allocated IpAddresses on the interface
Params:
{instance_id} in URI 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. {interface_id} in URI is the id of an existing interface in Melange
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When network for a given network_id and tenant_id is not found]
Verb URI Description POST /ipam/tenants/{tenant_id}/networks/{network_id}/interfaces/{interface_id}/ip_allocations Allocate an IPv4 and IPv6 address from a tenant’s network.
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]
JSON Response Example:
{
"ip_addresses": [
{
"address": "192.168.1.0",
"id": "e9394108-4276-4965-8621-52bfa00464b5",
"interface_id": "123",
"ip_block": {
"broadcast": "192.168.1.255",
"cidr": "192.168.1.0/24",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "192.168.1.1",
"id": "d14b95da-261f-4b7e-90a1-0e2902c5f454",
"ip_routes": [],
"netmask": "255.255.255.0"
},
"version": 4
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/networks/{network_id}/interfaces/{interface_id}/ip_allocations Get all 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]
JSON Response Example:
{
"ip_addresses": [
{
"address": "10.0.0.0",
"id": "8100fe1f-f184-4814-a66b-fe21fb5a0439",
"interface_id": "123",
"ip_block": {
"broadcast": "10.255.255.255",
"cidr": "10.0.0.0/8",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "10.0.0.1",
"id": "9aa72404-f5de-4bef-848f-cc8cbe12b9e8",
"ip_routes": [],
"netmask": "255.0.0.0"
},
"version": 4
},
{
"address": "00fe:0000:0000:0000:0000:0000:ffdd:eeff",
"id": "fcf37931-7a4c-4a02-a939-1d09b66ecb9b",
"interface_id": "123",
"ip_block": {
"broadcast": "fe::ffff:ffff",
"cidr": "fe::/96",
"dns1": "8.8.8.8",
"dns2": "8.8.4.4",
"gateway": "fe::1",
"id": "7ab2f803-a5d7-4d77-bb42-1eb1e8732e93",
"ip_routes": [],
"netmask": "96"
},
"version": 6
}
]
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/networks/{network_id}/interfaces/{interface_id}/ip_allocations Delete all 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]
Tracking NAT information is designed to assist in the implementation and tracking of floating IPs.
Verb URI Description GET /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_globals List all outside globals for a local ip_address
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]
Verb URI Description GET /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_locals List all outside globals for a local ip_address
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]
Verb URI Description POST /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_globals Finds local IpAddress from given ip_block_id and address and creates IpAddresses passed in params as its inside global.
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]
Verb URI Description POST /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_globals Finds global IpAddress from given ip_block_id and address and adds IpAddresses passed in params as its inside local.
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]
Verb URI Description DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_globals/{inside_globals_address} Finds global IpAddress from given ip_block_id and address and adds IpAddresses passed in params as its inside 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]
Verb URI Description DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_locals/{inside_locals_address} 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_globals_address in URL.
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]
Verb URI Description DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_locals/{address} 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 in URL.
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]
Verb URI Description DELETE /ipam/ip_blocks/{ip_block_id}/ip_addresses/{address}/inside_locals Finds the inside ip_address from given ip_block_id and address, and remove all its inside local ip_addresses.
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]
Verb URI Description GET /ipam/tenants/{tenant_id}/policies List all policies of a tenant.
Params:
None
Response Codes:
Normal Response code: 200
JSON Response Example:
{
"policies": [
{
"created_at": "2011-12-01T09:06:10",
"description": "policy_desc",
"id": "2f730874-2088-4f91-87fb-63792c753971",
"name": "rax_policy",
"tenant_id": "RAX",
"updated_at": "2011-12-01T09:06:10"
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/policies/:(id) Get details of the policy.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When Policy for given id and tenant_id does not exists]
JSON Response:
{
"policy": {
"created_at": "2011-12-01T09:06:10",
"description": "policy_desc",
"id": "2f730874-2088-4f91-87fb-63792c753971",
"name": "rax_policy",
"tenant_id": "RAX",
"updated_at": "2011-12-01T09:06:10"
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/policies Create an ip policy for the tenant
Params:
{
"policy": {
"name": "infrastructure"
"description": "Policy to disallow allocation of infrastruture ips"
}
}
‘name’ : Name of the policy.[Mandatory]
‘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]
JSON Response:
{
"policy": {
"created_at": "2011-12-01T09:06:10",
"description": "policy_desc",
"id": "2f730874-2088-4f91-87fb-63792c753971",
"name": "rax_policy",
"tenant_id": "RAX",
"updated_at": "2011-12-01T09:06:10"
}
}
Verb URI Description PUT /ipam/tenants/{tenant_id}/policies/:(id) Update name or descritopn of a tenant’s ip policy.
Params:
{
"policy": {
"name": "infrastructure"
"description": "Policy to disallow allocation of infrastruture ips"
}
}
‘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]
JSON Response Example:
{
"policy": {
"created_at": "2011-12-01T09:06:10",
"description": "policy_desc",
"id": "2f730874-2088-4f91-87fb-63792c753971",
"name": "rax_policy",
"tenant_id": "RAX",
"updated_at": "2011-12-01T09:06:10"
}
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/policies/:(id) Delete a tenant’s ip policy
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When Policy for given id and tenant_id does not exists]
Verb URI Description GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges List all unusable ip ranges of a tenant’s policy.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When policy doesn’t exist]
JSON Response Example:
{
"ip_ranges": [
{
"created_at": "2011-12-01T10:26:23",
"id": "2382fcc2-f90a-44fb-8607-c92e35280b85",
"length": 2,
"offset": 0,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:26:23"
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges Get details of a policy’s unusable ip range.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When Policy or IP Range doesn’t exist]
JSON Response Example:
{
"ip_range": {
"created_at": "2011-12-01T10:26:23",
"id": "2382fcc2-f90a-44fb-8607-c92e35280b85",
"length": 2,
"offset": 0,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:26:23"
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges Create a unusable ip range in tenant’s policy.
Params:
{
"ip_range": {
"offset": "10",
"length": "2",
}
}
‘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]
JSON Response Example:
{
"ip_range": {
"created_at": "2011-12-01T10:26:23",
"id": "2382fcc2-f90a-44fb-8607-c92e35280b85",
"length": 2,
"offset": 0,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:26:23"
}
}
Verb URI Description PUT /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Update details of a policy’s unusable IP range
Params:
{
"ip_range": {
"offset": "10",
"length": "2",
}
}
‘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]
JSON Response Example:
{
"ip_range": {
"created_at": "2011-12-01T10:26:23",
"id": "2382fcc2-f90a-44fb-8607-c92e35280b85",
"length": 2,
"offset": 0,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:26:23"
}
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_ranges/:(id) Delete a policy’s unusable ip range
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When Policy or IP range doesn’t exist]
Verb URI Description GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets List all unusable ip octets of a tenant’s policy.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When Policy doesn’t exist]
JSON Response Example:
{
"ip_octets": [
{
"created_at": "2011-12-01T10:37:30",
"id": "0e7a873e-0fe6-41e9-9f58-1182db01309c",
"octet": 123,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:37:30"
}
]
}
Verb URI Description GET /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Get details of a tenant’s policy’s unusable ip octet.
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When Policy or IP octet doesn’t exist]
JSON Response Example:
{
"ip_octet": {
"created_at": "2011-12-01T10:37:30",
"id": "0e7a873e-0fe6-41e9-9f58-1182db01309c",
"octet": 123,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:37:30"
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets Create a unusable ip octet in tenant’s policy.
Params:
‘octet’: integer [Mandatory, Should be 0-255]
Response Codes:
Normal Response code: 201
Error - 404 Not Found [When Policy doesn’t exist]
JSON Response Example:
{
"ip_octet": {
"created_at": "2011-12-01T10:37:30",
"id": "0e7a873e-0fe6-41e9-9f58-1182db01309c",
"octet": 123,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:37:30"
}
}
Verb URI Description POST /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Update details of a tenant’s policy’s unusable ip octet.
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]
JSON Response Example:
{
"ip_octet": {
"created_at": "2011-12-01T10:37:30",
"id": "0e7a873e-0fe6-41e9-9f58-1182db01309c",
"octet": 123,
"policy_id": "2f730874-2088-4f91-87fb-63792c753971",
"updated_at": "2011-12-01T10:37:30"
}
}
Verb URI Description DELETE /ipam/tenants/{tenant_id}/policies/{policy_id}/unusable_ip_octets/:(id) Delete a tenant’s policy’s unusable ip octet
Params:
None
Response Codes:
Normal Response code: 200
Error - 404 Not Found [When Policy or IP octet doesn’t exist]
Verb URI Description GET /ipam/mac_address_ranges List all mac address ranges.
Params:
None
Response Codes:
Normal Response code: 200
JSON Response Example:
{
"mac_address_ranges": [
{
"created_at": "2011-12-01T10:37:30",
"id": "0e7a873e-0fe6-41e9-9f58-1182db01309c",
"cidr": "BC:76:4E:20:00:00/27",
"updated_at": "2011-12-01T10:37:30"
},
{
"created_at": "2011-12-01T10:37:30",
"id": "0e7a873e-0fe6-41e9-9f58-1182db01309c",
"cidr": "CD:76:4E:20:00:00/27",
"updated_at": "2011-12-01T10:37:30"
},
]
}
Verb URI Description POST /ipam/mac_address_ranges Create a mac address range.
Params:
{
"mac_address_range": {
"cidr": "ab-bc-cd-12-23-34/40"
}
}
‘cidr’: The “cidr” that defines the range of mac addresses
Response Codes:
Normal Response code: 201
Error - 400 Bad Request [When required parameters are not present or field validation fails]
JSON Response Example:
{
"mac_address_range": {
"created_at": "2011-12-01T10:37:30",
"id": "0e7a873e-0fe6-41e9-9f58-1182db01309c",
"cidr": "BC:76:4E:20:00:00/27",
"updated_at": "2011-12-01T10:37:30"
}
}