Supported APIs for Brahmaputra

JIRA: PROMISE-62

Change-Id: I963bd25bf2a9daf431a1a81dc873f00e96362d72
Signed-off-by: Bertrand Souville <souville@docomolab-euro.com>
(cherry picked from commit cf6c391ec00de20f6173c8436ff6c705b67e5291)

3 files changed, 610 insertions, 1 deletions

diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst
index 5337ff5..3bf0777 100644
--- a/docs/requirements/index.rst
+++ b/docs/requirements/index.rst
@@ -45,4 +45,5 @@ Promise: Resource Management
    references.rst
    annex1.rst
    schemas.rst
+   supported_apis.rst
    revision.rst
diff --git a/docs/requirements/revision.rst b/docs/requirements/revision.rst
index 0bc4b32..2c4cb54 100644
--- a/docs/requirements/revision.rst
+++ b/docs/requirements/revision.rst
@@ -1,4 +1,4 @@
-ANNEX C: Document revision
+ANNEX D: Document revision
 ==========================
 
 +---------+-----------------------------------------+
@@ -25,3 +25,7 @@ ANNEX C: Document revision
 | 1.0.5   | JIRA: PROMISE-61                        |
 |         |  - Updated Promise Yang Schema          |
 +---------+-----------------------------------------+
+| 1.0.6   | JIRA: PROMISE-62                        |
+|         |  - Supported APIs for Brahmaputra       |
++---------+-----------------------------------------+
+
diff --git a/docs/requirements/supported_apis.rst b/docs/requirements/supported_apis.rst
new file mode 100644
index 0000000..50a47ab
--- /dev/null
+++ b/docs/requirements/supported_apis.rst
@@ -0,0 +1,604 @@
+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": []
+      }
+