Jump to: navigation, search

MelangeAPIBase

Revision as of 16:13, 8 July 2011 by JameyMeredith (talk)

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)
Retrieved from "https://wiki.openstack.org/w/index.php?title=MelangeAPIBase&oldid=8536"