12. ANNEX C: Supported APIS

12.1. Add Provider

Register a new resource provider (e.g. OpenStack) into reservation system.

Request parameters

Name Type Description
provider-type Enumeration Name of the resource provider
endpoint URI Targer URL end point for the resource provider
username String User name
password String Password
region String Specified region for the provider
tenant.id String Id of the tenant
tenant.name String Name of the tenant

Response parameters

Name Type Description
provider-id String Id of the new resource provider
result Enumeration Result info
POST /add-provider

Example request:

POST /add-provider HTTP/1.1
Accept: application/json

{
  "provider-type": "openstack",
  "endpoint": "http://10.0.2.15:5000/v2.0/tokens",
  "username": "promise_user",
  "password": "******",
  "tenant": {
     "name": "promise"
  }
}

Example response:

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

{
  "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
  "result": "ok"
}

12.2. Create Reservation

Make a request to the reservation system to reserve resources.

Request parameters

Name Type Description
zone String Id to an availability zone
start DateTime Timestamp when the consumption of reserved resources can begin
end DateTime Timestamp when the consumption of reserved resources should end
capacity.cores int16 Amount of cores to be reserved
capacity.ram int32 Amount of RAM to be reserved
capacity.instances int16 Amount of instances to be reserved
capacity.addresses int32 Amount of public IP addresses to be reserved
elements ResourceElement List of pre-existing resource elements to be reserved

Response parameters

Name Type Description
reservation-id String Id of the reservation
result Enumeration Result info
message String Output message
POST /create-reservation

Example request:

POST /create-reservation HTTP/1.1
Accept: application/json

{
   "capacity": {
      "cores": "5",
      "ram": "25600",
      "addresses": "3",
      "instances": "3"
   },
   "start": "2016-02-02T00:00:00Z",
   "end": "2016-02-03T00:00:00Z"
}

Example response:

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

{
  "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619",
  "result": "ok",
  "message": "reservation request accepted"
}

12.3. Update Reservation

Update reservation details for an existing reservation.

Request parameters

Name Type Description
reservation-id String Id of the reservation to be updated
zone String Id to an availability zone
start DateTime Updated timestamp when the consumption of reserved resources can begin
end DateTime Updated timestamp when the consumption of reserved resources should end
capacity.cores int16 Updated amount of cores to be reserved
capacity.ram int32 Updated amount of RAM to be reserved
capacity.instances int16 Updated amount of instances to be reserved
capacity.addresses int32 Updated amount of public IP addresses to be reserved
elements ResourceElement Updated list of pre-existing resource elements to be reserved

Response parameters

Name Type Description
result Enumeration Result info
message String Output message
POST /update-reservation

Example request:

POST /update-reservation HTTP/1.1
Accept: application/json

{
   "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619",
   "capacity": {
      "cores": "1",
      "ram": "5120",
      "addresses": "1",
      "instances": "1"
   }
}

Example response:

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

{
  "result": "ok",
  "message": "reservation update successful"
}

12.4. Cancel Reservation

Cancel the reservation.

Request parameters

Name Type Description
reservation-id String Id of the reservation to be canceled

Response parameters

Name Type Description
result Enumeration Result info
message String Output message
POST /cancel-reservation

Example request:

POST /cancel-reservation HTTP/1.1
Accept: application/json

{
  "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619"
}

Example response:

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

{
  "result": "ok",
  "message": "reservation canceled"
}

12.5. Query Reservation

Query the reservation system to return matching reservation(s).

Request parameters

Name Type Description
zone String Id to an availability zone
show-utilization Boolean Show capacity utilization
without ResourceCollection Excludes specified collection identifiers from the result
elements.some ResourceElement Query for ResourceCollection(s) that contain some or more of these element(s)
elements.every ResourceElement Query for ResourceCollection(s) that contain all of these element(s)
window.start DateTime Matches entries that are within the specified start/end window
window.end DateTime  
wndow.scope Enumeration Matches entries that start {and/or} end within the time window

Response parameters

Name Type Description
reservations ResourceReservation List of matching reservations
utilization CapacityUtilization Capacity utilization over time
POST /query-reservation

Example request:

POST /query-reservation HTTP/1.1
Accept: application/json

{
   "show-utilization": false,
   "window": {
      "start": "2016-02-01T00:00:00Z",
      "end": "2016-02-04T00:00:00Z"
   }
}

Example response:

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

{
  "reservations": [
    "269b2944-9efv-41e0-b067-6898221e8619"
  ],
  "utilization": []
}

12.6. Create Instance

Create an instance of specified resource(s) utilizing capacity from the pool.

Request parameters

Name Type Description
provider-id String Id of the resource provider
reservation-id String Id of the resource reservation
name String Name of the instance
image String Id of the image
flavor String Id of the flavor
networks Uuid List of network uuids

Response parameters

Name Type Description
instance-id String Id of the instance
result Enumeration Result info
message String Output message
POST /create-instance

Example request:

POST /create-instance HTTP/1.1
Accept: application/json

{
  "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
  "name": "vm1",
  "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8",
  "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902"
}

Example response:

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

{
  "instance-id": "82572779-896b-493f-92f6-a63008868250",
  "result": "ok",
  "message": "created-instance request accepted"
}

12.7. Destroy Instance

Destroy an instance of resource utilization and release it back to the pool.

Request parameters

Name Type Description
instance-id String Id of the instance to be destroyed

Response parameters

Name Type Description
result Enumeration Result info
message String Output message
POST /destroy-instance

Example request:

POST /destroy-instance HTTP/1.1
Accept: application/json

{
   "instance-id": "82572779-896b-493f-92f6-a63008868250"
}

Example response:

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

{
  "result": "ok",
  "message": "instance destroyed and resource released back to pool"
}

12.8. Decrease Capacity

Decrease total capacity for the reservation system for a given time window.

Request parameters

Name Type Description
source String Id of the resource container
start DateTime Start/end defines the time window when total capacity is decreased
end DateTime  
capacity.cores int16 Decreased amount of cores
capacity.ram int32 Decreased amount of RAM
capacity.instances int16 Decreased amount of instances
capacity.addresses int32 Decreased amount of public IP addresses

Response parameters

Name Type Description
pool-id String Id of the resource pool
result Enumeration Result info
message String Output message
POST /decrease-capacity

Example request:

POST /decrease-capacity HTTP/1.1
Accept: application/json

{
   "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f",
   "capacity": {
      "cores": "3",
      "ram": "5120",
      "addresses": "1"
   }
}

Example response:

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

{
   "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
   "result": "ok",
   "message": "capacity decrease successful"
}

12.9. Increase Capacity

Increase total capacity for the reservation system for a given time window.

Request parameters

Name Type Description
source String Id of the resource container
start DateTime Start/end defines the time window when total capacity is increased
end DateTime  
capacity.cores int16 Increased amount of cores
capacity.ram int32 Increased amount of RAM
capacity.instances int16 Increased amount of instances
capacity.addresses int32 Increased amount of public IP addresses

Response parameters

Name Type Description
pool-id String Id of the resource pool
result Enumeration Result info
message String Output message
POST /increase-capacity

Example request:

POST /increase-capacity HTTP/1.1
Accept: application/json

{
   "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f",
   "capacity": {
       "cores": "20",
       "ram": "51200",
       "instances": "10",
       "addresses": "10"
   }
}

Example response:

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

{
   "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
   "result": "ok",
   "message": "capacity increase successful"
}

12.10. Query Capacity

Query for capacity information about a specified resource collection.

Request parameters

Name Type Description
capacity Enumeration Return total or reserved or available or usage capacity information
zone String Id to an availability zone
show-utilization Boolean Show capacity utilization
without ResourceCollection Excludes specified collection identifiers from the result
elements.some ResourceElement Query for ResourceCollection(s) that contain some or more of these element(s)
elements.every ResourceElement Query for ResourceCollection(s) that contain all of these element(s)
window.start DateTime Matches entries that are within the specified start/end window
window.end DateTime  
window.scope Enumeration Matches entries that start {and/or} end within the time window

Response parameters

Name Type Description
collections ResourceCollection List of matching collections
utilization CapacityUtilization Capacity utilization over time
POST /query-capacity

Example request:

POST /query-capacity HTTP/1.1
Accept: application/json

{
  "show-utilization": false
}

Example response:

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "collections": [
    "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
  ],
  "utilization": []
}