Differences

This shows you the differences between two versions of the page.

--- promise:apis_b_release [2015/11/27 11:14]
Bertrand Souville
+++ promise:apis_b_release [2016/02/01 11:06] (current)
Bertrand Souville
@@ Line 1: / Line 1: @@
 ==== Supported APIs for B-Release ====
+**1. Add Provider**
-. Add Provider
+Register a new resource provider (e.g. OpenStack) into reservation system.
-Register a new resource provider (e.g. OpenStack) into reservation system. See pkgcloud lib for list of supported providers.
+Request parameters
+^ Name                   ^ Type             ^ Description                                   ^
+| provider-type          | Enumeration      | Name of the resource provider                 |
+| endpoint               | URI              | Target URL endpoint 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                            |
-**Request parameters**
+Response parameters
-^  Parameters            ^  Types            ^  Description  ^
+^ Name                   ^ Type             ^  Description                    ^
-| provider-type          |  Enumeration      | Name of the resource provider |
+| provider-id            | String           | Id of the new resource provider |
-| endpoint               |  URI              | Target URL endpoint for the resource provider |
+| result                 | Enumeration      | Result info                     |
-| username               |  String           | User name |
-| password               |  String           | Password |
-| region                 |  String           | Specified region for the provider (Optional) |
-| tenant.id              |  String           | Id of the tenant |
-| tenant.name            |  String           | Name of the tenant |
-**Response parameters**
-^  Parameters            ^  Types            ^  Description  ^
-| provider-id            |  String           |  Id of the new resource provider |
-| result                 |  Enumeration      |  Result message (e.g. OK, ERROR} |
 **Example request**
@@ Line 25: / Line 24: @@
       "provider-type": "openstack",
       "endpoint": "http://10.0.2.15:5000/v2.0/tokens",
-      "username": "admin",
+      "username": "promise_user",
       "password": "******",
       "tenant": {
-         "id": "0d36689a21e24a15a9c543ec8dd86510",
+         "name": "promise"
-         "name": "admin"
       }
     }
@@ Line 36: / Line 34: @@
     {
-      "provider-id": "1bc96b9c-c316-4854-aa10-9d2bea35508f",
+      "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
       "result": "ok"
     }
-. Create Reservation
+**2. Create Reservation**
-Make a request to the reservation system to reserve resources
+Make a request to the reservation system to reserve resources.
-**Request parameters**
+Request parameters
-^  Parameters            ^  Types            ^  Description  ^
+^ Name                   ^ Type              ^ Description                                                    ^
-| zone                   | String            | Id to an availability zone (Optional) |
+| zone                   | String            | Id to an availability zone                                      |
-| start                  | DateTime          | Timestamp when the consumption of reserved resources can begin (Optional) |
+| start                  | DateTime          | Timestamp when the consumption of reserved resources can begin  |
-| end                    | DateTime          | Timestamp when the consumprtion of reserved resources should end (Optional) |
+| end                    | DateTime          | Timestamp when the consumption of reserved resources should end |
-| capacity.cores         | int16             | Amount of cores to be reserved (Default: 0) |
+| capacity.cores         | int16             | Amount of cores to be reserved                                  |
-| capacity.ram           | int32             | Amount of RAM (in MB) to be reserved (Default: 0) |
+| capacity.ram           | int32             | Amount of RAM to be reserved                                    |
-| capacity.instances     | int16             | Amount of instances to be reserved (Default: 0) |
+| capacity.instances     | int16             | Amount of instances to be reserved                              |
-| capacity.networks      | int16             | Amount of networks to be reserved (Default: 0) |
+| capacity.addresses     | int32             | Amount of public IP addresses to be reserved                    |
-| capacity.ports         | int16             | Amount of ports to be reserved (Default: 0) |
+| elements               | ResourceElement   | List of pre-existing resource elements to be reserved           |
-| capacity.routers       | int16             | Amount of routers to be reserved (Default: 0) |
-| capacity.subnets       | int16             | Amount of subnets to be reserved (Default: 0) |
-| capacity.addresses     | int32             | Amount of public IP addresses to be reserved (Default: 0) |
-| capacity.gigabytes     | int32             | Amount of gigabytes to be reserved (Default: 0) |
-| capacity.snapshots     | int16             | Amount of snapshots to be reserved (Default: 0) |
-| capacity.volumes       | int16             | Amount of volumes to be reserved (Default: 0) |
-| elements               | ResourceElement   | Amount of pre-existing resource elements (e.g. resource reservation) to be reserved |
-**Response parameters**
+Response parameters
-^  Parameters            ^  Types            ^  Description  ^
+^ Name                   ^ Type              ^ Description           ^
-| reservation-id         |  String           | Id of the reservation |
+| reservation-id         | String            | Id of the reservation |
-| result                 | Enumeration       | Result message (e.g. OK, ERROR, CONFLICT) |
+| result                 | Enumeration       | Result info           |
-| message                | String            | Output message (e.g. "reservation request accepted" |
+| message                | String            | Output message        |
 **Example request**
@@ Line 73: / Line 64: @@
        "capacity": {
           "cores": "5",
-          "ram": 0
+          "ram": "25600",
-          "instances": 0
-          "networks": 0,
-          "ports": 0
           "addresses": "3",
-          "gigabytes": "10,
+          "instances": "3"
-          "snapshots": 0,
-          "volumes": 0
       },
-      "elements": []
+      "start": "2016-02-02T00:00:00Z",
+      "end": "2016-02-03T00:00:00Z"
     }
-** Example response**
+**Example response**
     {
-       "reservation-id": "f6f7d56a-4740-48fe-b197-42a7001beb95",
+       "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619",
        "result": "ok",
        "message": "reservation request accepted"
     }
+**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 |
+**Example request**
+    {
+       "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619",
+       "capacity": {
+          "cores": "1",
+          "ram": "5120",
+          "addresses": "1",
+          "instances": "1"
+       }
+    }
+**Example response**
+    {
+       "result": "ok",
+       "message": "reservation update successful"
+    }
+**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 |
+**Example request**
+    {
+      "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619"
+    }
+**Example response**
+   {
+     "result": "ok",
+     "message": "reservation canceled"
+   }
+**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           |                                                                      |
+| window.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 |
+**Example request**
+   {
+     "show-utilization": false,
+     "window": {
+        "start": "2016-02-01T00:00:00Z",
+        "end": "2016-02-04T00:00:00Z"
+     }
+   }
+**Example response**
+    {
+       "reservations": [
+         "269b2944-9efv-41e0-b067-6898221e8619"
+       ],
+       "utilization": []
+    }
+**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                |
+| 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                 |
+**Example request**
+   {
+     "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
+     "name": "vm1",
+     "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8",
+     "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902"
+   }
+**Example response**
+    {
+       "instance-id": "82572779-896b-493f-92f6-a63008868250",
+       "result": "ok",
+       "message": "created-instance request accepted"
+    }
+**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                 |
+**Example request**
+   {
+     "instance-id": "82572779-896b-493f-92f6-a63008868250"
+   }
+**Example response**
+    {
+       "result": "ok",
+       "message": "instance destroyed and resource released back to pool"
+    }
+**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           |
+**Example request**
+   {
+     "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f",
+     "capacity": {
+          "cores": "3",
+          "ram": "5120",
+          "addresses": "1"
+      }
+   }
+**Example response**
+    {
+       "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
+       "result": "ok",
+       "message": "capacity decrease successful"
+    }
+**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           |
+**Example request**
+   {
+     "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f",
+     "capacity": {
+          "cores": "20",
+          "ram": "51200",
+          "instances": "10",
+          "addresses": "10"
+      }
+   }
+**Example response**
+    {
+       "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
+       "result": "ok",
+       "message": "capacity increase successful"
+    }
+**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 |
+**Example request**
+   {
+     "show-utilization": false
+   }
+**Example response**
+    {
+       "collections": [
+         "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
+       ],
+       "utilization": []
+    }

Wiki

User Tools

Site Tools

Differences

Page Tools