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": []
}