--- /dev/null
+ANNEX C: Supported APIS
+=======================
+
+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
+============================ =========== ==============================================
+
+.. http:post:: /add-provider
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ 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**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
+ "result": "ok"
+ }
+
+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
+============================ =========== ==============================================
+
+.. http:post:: /create-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ 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**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619",
+ "result": "ok",
+ "message": "reservation request accepted"
+ }
+
+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
+============================ =========== ==============================================
+
+.. http:post:: /update-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ 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**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "result": "ok",
+ "message": "reservation update successful"
+ }
+
+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
+============================ =========== ==============================================
+
+.. http:post:: /cancel-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /cancel-reservation HTTP/1.1
+ Accept: application/json
+
+ {
+ "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "result": "ok",
+ "message": "reservation canceled"
+ }
+
+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
+============================ =================== ================================
+
+.. http:post:: /query-reservation
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ 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**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "reservations": [
+ "269b2944-9efv-41e0-b067-6898221e8619"
+ ],
+ "utilization": []
+ }
+
+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
+============================ =============== ==============================================
+
+Response parameters
+
+============================ =========== ==============================================
+Name Type Description
+============================ =========== ==============================================
+instance-id String Id of the instance
+result Enumeration Result info
+message String Output message
+============================ =========== ==============================================
+
+.. http:post:: /create-instance
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ 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**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "instance-id": "82572779-896b-493f-92f6-a63008868250",
+ "result": "ok",
+ "message": "created-instance request accepted"
+ }
+
+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
+============================ =========== ==============================================
+
+.. http:post:: /destroy-instance
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /destroy-instance HTTP/1.1
+ Accept: application/json
+
+ {
+ "instance-id": "82572779-896b-493f-92f6-a63008868250"
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "result": "ok",
+ "message": "instance destroyed and resource released back to pool"
+ }
+
+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
+============================ =========== ==============================================
+
+.. http:post:: /decrease-capacity
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ 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**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
+ "result": "ok",
+ "message": "capacity decrease successful"
+ }
+
+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
+============================ =========== ==============================================
+
+.. http:post:: /increase-capacity
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ 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**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+
+ {
+ "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
+ "result": "ok",
+ "message": "capacity increase successful"
+ }
+
+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
+============================ =================== ================================
+
+.. http:post:: /query-capacity
+ :noindex:
+
+ **Example request**:
+
+ .. sourcecode:: http
+
+ POST /query-capacity HTTP/1.1
+ Accept: application/json
+
+ {
+ "show-utilization": false
+ }
+
+ **Example response**:
+
+ .. sourcecode:: http
+
+ HTTP/1.1 201 CREATED
+ Content-Type: application/json
+
+ {
+ "collections": [
+ "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
+ ],
+ "utilization": []
+ }
+
Code Review / promise.git / commitdiff