Jump to: navigation, search

Blazar/REST API

< Blazar
Revision as of 13:06, 3 February 2014 by Dina Belova (talk | contribs)

General API information

This page contains base information about the Climate REST API design, including operations with different Climate resource types and examples of possible requests and responses. Climate supports JSON data serialization format, which means that requests with non empty body have to contain "application/json" Content-Type header or it should be added ".json" extension to the resource name in the request.

This should look like the following:

   GET /v1/{tenant_id}/leases.json

or

   GET /v1/{tenant_id}/leases
   Accept: application/json

Leases

Lease is the main abstraction for the user in the Climate case. Lease means some kind of contract where start time, end time and resources to be reserved are mentioned.

Lease ops

Verb URI Description
GET
/v1/leases 
Lists all leases registered in Climate for tenant defined in headers.
POST 
/v1/leases 
Create new lease with passed parameters.
GET 
/v1/leases/{lease_id}
Shows information about specified lease.
PUT 
/v1/leases/{lease_id}
Updates specified lease (only name modification and prolonging are possible).
DELETE
/v1/leases/{lease_id}
Deletes specified lease and frees all reserved resources.

List all leases

 /v1/leases
  • Normal Response Code: 200 (OK)
  • Returns the list of all leases.
  • Does not require a request body.


Example

Request:

  GET http://climate_node:1234/v1/leases

Response:

   HTTP/1.1 200 OK
   Content-Type: application/json

{
   "leases": [
       {
           "id": "aaaa-bbbb-cccc-dddd",
           "name": "lease_foo_1",
           "start_date": "1234",
           "end_date": "2345",
           "reservations": [{...}],
           "events": [{...}]
       },
       {
           "id": "eeee-ffff-gggg-hhhh",
           "name": "lease_foo_2",
           "start_date": "1234",
           "end_date": "2345",
           "reservations": [{...}],
           "events": [{...}]
       }
   ]
}

Create new lease

   /v1/leases
  • Normal Response Code: 202 (ACCEPTED)
  • Returns the information about created lease.
  • Requires a request body.


Example

Request:

   POST http://climate_node:1234/v1/leases

{
   "name": "lease_foo",
   "start_date": "1234",
   "end_date": "2345",
   "reservations": [
       {
           "resource_id": "1234-1234-1234",
           "resource_type": "virtual:instance",
           "status": "Reserved"
       }
   ]
}

Response:

   HTTP/1.1 202 ACCEPTED
   Content-Type: application/json

 {
   "id": "aaaa-bbbb-cccc-dddd",
   "name": "lease_foo",
   "start_date": "1234",
   "end_date": "2345",
   "reservations": [
       {
           "id": "fake_resource_id",
           "resource_id": "1234-1234-1234",
           "resource_type": "virtual:instance",
           "status": "Reserved"
       }
   ],
   "events": [
       {
           "id": "fake_event_id",
           "event_type": "start_lease",
           "event_date": "1234"
       },
       {
           "id": "fake_event_id",
           "event_type": "end_lease",
           "event_date": "2345"
       }
   ]
}

Show info about lease

   /v1/leases/{lease_id}
  • Normal Response Code: 200 (OK)
  • Returns the information about specified lease.
  • Does not require a request body.


Example

Request:

   GET http://climate_node:1234/v1/leases/aaaa-bbbb-cccc-dddd

Response:

   HTTP/1.1 200 OK
   Content-Type: application/json

{
   "id": "aaaa-bbbb-cccc-dddd",
   "name": "lease_foo_1",
   "start_date": "1234",
   "end_date": "2345",
   "reservations": [
       {
           "id": "fake_resource_id_1",
           "lease_id": "aaaa-bbbb-cccc-dddd",
           "resource_id": "1234-1234-1234",
           "resource_type": "virtual:instance",
           "status": "Reserved"
       }
   ],
   "events": [
       {
           "id": "fake_event_id",
           "event_type": "start_lease",
           "event_date": "1234"
       },
       {
           "id": "fake_event_id",
           "event_type": "end_lease",
           "event_date": "2345"
       }
   ]
}

Update existing lease

   /v1/leases/{lease_id}
  • Normal Response Code: 202 ACCEPTED
  • Returns the updated information about lease.
  • Requires a request body.


Example

Request:

   PUT http://climate_node:1234/v1/leases/aaaa-bbbb-cccc-dddd

   
{    
   "name": "new_name",
   "end_date": "new_date",
}

Response:

   HTTP/1.1 202 ACCEPTED
   Content-Type: application/json

{
   "id": "aaaa-bbbb-cccc-dddd",
   "name": "new_name",
   "start_date": "1234",
   "end_date": "new_date",
   "reservations": [{...}],
   "events": [{...}]
}

Delete existing lease

   /v1/leases/{lease_id}
  • Normal Response Code: 204 NO CONTENT
  • Does not require a request body.


Example

Request:

   DELETE http://climate_node:1234/v1/leases/aaaa-bbbb-cccc-dddd

Response:

   HTTP/1.1 204 ACCEPTED
   Content-Type: application/json

Hosts

TBD

Plugins

Plugins are working with different resources types. Technically speaking they are implemented using stevedore extensions.

Plugins ops

Verb URI Description
GET
/v1/plugins 
Lists all plugins used now in Climate.

List plugins

   /v1/plugins

Example

Request:

   GET http://climate_node:1234/v1/plugins

Response:

   HTTP/1.1 200 OK
   Content-Type: application/json

{
   "plugins": [
       {
           "name": "basic_vm_plugin",
           "resource_type": "virtual:instance",
           "description": "Works with Nova instances. Unshelves VM when lease begins, supports VM snapshoting, suspending and deletion when lease ends."
       },
       {
           "name": "physical_host_plugin",
           "resource_type": "physical:host",
           "description": "Works with compute hosts. Creates aggregate with reserved hosts on lease start and returns them back to free pool on lease end."
       }
   ]
}