docs/requirements/supported_apis.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4 ANNEX C: Supported APIS
   5 =======================
   6
   7 Add Provider
   8 ------------
   9
  10 Register a new resource provider (e.g. OpenStack) into reservation system.
  11
  12 Request parameters
  13
  14 ============================ =========== ==============================================
  15 Name                         Type        Description
  16 ============================ =========== ==============================================
  17 provider-type                Enumeration Name of the resource provider
  18 endpoint                     URI         Targer URL end point for the resource provider
  19 username                     String      User name
  20 password                     String      Password
  21 region                       String      Specified region for the provider
  22 tenant.id                    String      Id of the tenant
  23 tenant.name                  String      Name of the tenant
  24 ============================ =========== ==============================================
  25
  26 Response parameters
  27
  28 ============================ =========== ==============================================
  29 Name                         Type        Description
  30 ============================ =========== ==============================================
  31 provider-id                  String      Id of the new resource provider
  32 result                       Enumeration Result info
  33 ============================ =========== ==============================================
  34
  35 .. http:post:: /add-provider
  36    :noindex:
  37
  38    **Example request**:
  39
  40    .. sourcecode:: http
  41
  42       POST /add-provider HTTP/1.1
  43       Accept: application/json
  44
  45       {
  46         "provider-type": "openstack",
  47         "endpoint": "http://10.0.2.15:5000/v2.0/tokens",
  48         "username": "promise_user",
  49         "password": "******",
  50         "tenant": {
  51            "name": "promise"
  52         }
  53       }
  54
  55    **Example response**:
  56
  57    .. sourcecode:: http
  58
  59       HTTP/1.1 200 OK
  60       Content-Type: application/json
  61
  62       {
  63         "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
  64         "result": "ok"
  65       }
  66
  67 Create Reservation
  68 ------------------
  69
  70 Make a request to the reservation system to reserve resources.
  71
  72 Request parameters
  73
  74 ============================ =============== ==============================================
  75 Name                         Type            Description
  76 ============================ =============== ==============================================
  77 zone                         String          Id to an availability zone
  78 start                        DateTime        Timestamp when the consumption of reserved
  79                                              resources can begin
  80 end                          DateTime        Timestamp when the consumption of reserved
  81                                              resources should end
  82 capacity.cores               int16           Amount of cores to be reserved
  83 capacity.ram                 int32           Amount of RAM to be reserved
  84 capacity.instances           int16           Amount of instances to be reserved
  85 capacity.addresses           int32           Amount of public IP addresses to be reserved
  86 elements                     ResourceElement List of pre-existing resource elements
  87                                              to be reserved
  88 ============================ =============== ==============================================
  89
  90 Response parameters
  91
  92 ============================ =========== ==============================================
  93 Name                         Type        Description
  94 ============================ =========== ==============================================
  95 reservation-id               String      Id of the reservation
  96 result                       Enumeration Result info
  97 message                      String      Output message
  98 ============================ =========== ==============================================
  99
 100 .. http:post:: /create-reservation
 101    :noindex:
 102
 103    **Example request**:
 104
 105    .. sourcecode:: http
 106
 107       POST /create-reservation HTTP/1.1
 108       Accept: application/json
 109
 110       {
 111          "capacity": {
 112             "cores": "5",
 113             "ram": "25600",
 114             "addresses": "3",
 115             "instances": "3"
 116          },
 117          "start": "2016-02-02T00:00:00Z",
 118          "end": "2016-02-03T00:00:00Z"
 119       }
 120
 121    **Example response**:
 122
 123    .. sourcecode:: http
 124
 125       HTTP/1.1 200 OK
 126       Content-Type: application/json
 127
 128       {
 129         "reservation-id": "269b2944-9efc-41e0-b067-6898221e8619",
 130         "result": "ok",
 131         "message": "reservation request accepted"
 132       }
 133
 134 Update Reservation
 135 ------------------
 136
 137 Update reservation details for an existing reservation.
 138
 139 Request parameters
 140
 141 ============================ =============== ==============================================
 142 Name                         Type            Description
 143 ============================ =============== ==============================================
 144 reservation-id               String          Id of the reservation to be updated
 145 zone                         String          Id to an availability zone
 146 start                        DateTime        Updated timestamp when the consumption of
 147                                              reserved resources can begin
 148 end                          DateTime        Updated timestamp when the consumption of
 149                                              reserved resources should end
 150 capacity.cores               int16           Updated amount of cores to be reserved
 151 capacity.ram                 int32           Updated amount of RAM to be reserved
 152 capacity.instances           int16           Updated amount of instances to be reserved
 153 capacity.addresses           int32           Updated amount of public IP addresses
 154                                              to be reserved
 155 elements                     ResourceElement Updated list of pre-existing resource elements
 156                                              to be reserved
 157 ============================ =============== ==============================================
 158
 159 Response parameters
 160
 161 ============================ =========== ==============================================
 162 Name                         Type        Description
 163 ============================ =========== ==============================================
 164 result                       Enumeration Result info
 165 message                      String      Output message
 166 ============================ =========== ==============================================
 167
 168 .. http:post:: /update-reservation
 169    :noindex:
 170
 171    **Example request**:
 172
 173    .. sourcecode:: http
 174
 175       POST /update-reservation HTTP/1.1
 176       Accept: application/json
 177
 178       {
 179          "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619",
 180          "capacity": {
 181             "cores": "1",
 182             "ram": "5120",
 183             "addresses": "1",
 184             "instances": "1"
 185          }
 186       }
 187
 188    **Example response**:
 189
 190    .. sourcecode:: http
 191
 192       HTTP/1.1 200 OK
 193       Content-Type: application/json
 194
 195       {
 196         "result": "ok",
 197         "message": "reservation update successful"
 198       }
 199
 200 Cancel Reservation
 201 ------------------
 202
 203 Cancel the reservation.
 204
 205 Request parameters
 206
 207 ============================ =============== ==============================================
 208 Name                         Type            Description
 209 ============================ =============== ==============================================
 210 reservation-id               String          Id of the reservation to be canceled
 211 ============================ =============== ==============================================
 212
 213 Response parameters
 214
 215 ============================ =========== ==============================================
 216 Name                         Type        Description
 217 ============================ =========== ==============================================
 218 result                       Enumeration Result info
 219 message                      String      Output message
 220 ============================ =========== ==============================================
 221
 222 .. http:post:: /cancel-reservation
 223    :noindex:
 224
 225    **Example request**:
 226
 227    .. sourcecode:: http
 228
 229       POST /cancel-reservation HTTP/1.1
 230       Accept: application/json
 231
 232       {
 233         "reservation-id": "269b2944-9efv-41e0-b067-6898221e8619"
 234       }
 235
 236    **Example response**:
 237
 238    .. sourcecode:: http
 239
 240       HTTP/1.1 200 OK
 241       Content-Type: application/json
 242
 243       {
 244         "result": "ok",
 245         "message": "reservation canceled"
 246       }
 247
 248 Query Reservation
 249 -----------------
 250
 251 Query the reservation system to return matching reservation(s).
 252
 253 Request parameters
 254
 255 ============================ ================== ==============================================
 256 Name                         Type               Description
 257 ============================ ================== ==============================================
 258 zone                         String             Id to an availability zone
 259 show-utilization             Boolean            Show capacity utilization
 260 without                      ResourceCollection Excludes specified collection identifiers
 261                                                 from the result
 262 elements.some                ResourceElement    Query for ResourceCollection(s) that contain
 263                                                 some or more of these element(s)
 264 elements.every               ResourceElement    Query for ResourceCollection(s) that contain
 265                                                 all of these element(s)
 266 window.start                 DateTime           Matches entries that are within the specified
 267                                                 start/end window
 268 window.end                   DateTime
 269 wndow.scope                  Enumeration        Matches entries that start {and/or} end
 270                                                 within the time window
 271 ============================ ================== ==============================================
 272
 273 Response parameters
 274
 275 ============================ =================== ================================
 276 Name                         Type                Description
 277 ============================ =================== ================================
 278 reservations                 ResourceReservation List of matching reservations
 279 utilization                  CapacityUtilization Capacity utilization over time
 280 ============================ =================== ================================
 281
 282 .. http:post:: /query-reservation
 283    :noindex:
 284
 285    **Example request**:
 286
 287    .. sourcecode:: http
 288
 289       POST /query-reservation HTTP/1.1
 290       Accept: application/json
 291
 292       {
 293          "show-utilization": false,
 294          "window": {
 295             "start": "2016-02-01T00:00:00Z",
 296             "end": "2016-02-04T00:00:00Z"
 297          }
 298       }
 299
 300    **Example response**:
 301
 302    .. sourcecode:: http
 303
 304       HTTP/1.1 200 OK
 305       Content-Type: application/json
 306
 307       {
 308         "reservations": [
 309           "269b2944-9efv-41e0-b067-6898221e8619"
 310         ],
 311         "utilization": []
 312       }
 313
 314 Create Instance
 315 ---------------
 316
 317 Create an instance of specified resource(s) utilizing capacity from the pool.
 318
 319 Request parameters
 320
 321 ============================ =============== ==============================================
 322 Name                         Type            Description
 323 ============================ =============== ==============================================
 324 provider-id                  String          Id of the resource provider
 325 reservation-id               String          Id of the resource reservation
 326 name                         String          Name of the instance
 327 image                        String          Id of the image
 328 flavor                       String          Id of the flavor
 329 networks                     Uuid            List of network uuids
 330 ============================ =============== ==============================================
 331
 332 Response parameters
 333
 334 ============================ =========== ==============================================
 335 Name                         Type        Description
 336 ============================ =========== ==============================================
 337 instance-id                  String      Id of the instance
 338 result                       Enumeration Result info
 339 message                      String      Output message
 340 ============================ =========== ==============================================
 341
 342 .. http:post:: /create-instance
 343    :noindex:
 344
 345    **Example request**:
 346
 347    .. sourcecode:: http
 348
 349       POST /create-instance HTTP/1.1
 350       Accept: application/json
 351
 352       {
 353         "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
 354         "name": "vm1",
 355         "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8",
 356         "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902"
 357       }
 358
 359    **Example response**:
 360
 361    .. sourcecode:: http
 362
 363       HTTP/1.1 200 OK
 364       Content-Type: application/json
 365
 366       {
 367         "instance-id": "82572779-896b-493f-92f6-a63008868250",
 368         "result": "ok",
 369         "message": "created-instance request accepted"
 370       }
 371
 372 Destroy Instance
 373 ----------------
 374
 375 Destroy an instance of resource utilization and release it back to the pool.
 376
 377 Request parameters
 378
 379 ============================ =============== ==============================================
 380 Name                         Type            Description
 381 ============================ =============== ==============================================
 382 instance-id                  String          Id of the instance to be destroyed
 383 ============================ =============== ==============================================
 384
 385 Response parameters
 386
 387 ============================ =========== ==============================================
 388 Name                         Type        Description
 389 ============================ =========== ==============================================
 390 result                       Enumeration Result info
 391 message                      String      Output message
 392 ============================ =========== ==============================================
 393
 394 .. http:post:: /destroy-instance
 395    :noindex:
 396
 397    **Example request**:
 398
 399    .. sourcecode:: http
 400
 401       POST /destroy-instance HTTP/1.1
 402       Accept: application/json
 403
 404       {
 405          "instance-id": "82572779-896b-493f-92f6-a63008868250"
 406       }
 407
 408    **Example response**:
 409
 410    .. sourcecode:: http
 411
 412       HTTP/1.1 200 OK
 413       Content-Type: application/json
 414
 415       {
 416         "result": "ok",
 417         "message": "instance destroyed and resource released back to pool"
 418       }
 419
 420 Decrease Capacity
 421 -----------------
 422
 423 Decrease total capacity for the reservation system for a given time window.
 424
 425 Request parameters
 426
 427 ============================ =============== ==============================================
 428 Name                         Type            Description
 429 ============================ =============== ==============================================
 430 source                       String          Id of the resource container
 431 start                        DateTime        Start/end defines the time window when total
 432                                              capacity is decreased
 433 end                          DateTime
 434 capacity.cores               int16           Decreased amount of cores
 435 capacity.ram                 int32           Decreased amount of RAM
 436 capacity.instances           int16           Decreased amount of instances
 437 capacity.addresses           int32           Decreased amount of public IP addresses
 438 ============================ =============== ==============================================
 439
 440 Response parameters
 441
 442 ============================ =========== ==============================================
 443 Name                         Type        Description
 444 ============================ =========== ==============================================
 445 pool-id                      String      Id of the resource pool
 446 result                       Enumeration Result info
 447 message                      String      Output message
 448 ============================ =========== ==============================================
 449
 450 .. http:post:: /decrease-capacity
 451    :noindex:
 452
 453    **Example request**:
 454
 455    .. sourcecode:: http
 456
 457       POST /decrease-capacity HTTP/1.1
 458       Accept: application/json
 459
 460       {
 461          "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f",
 462          "capacity": {
 463             "cores": "3",
 464             "ram": "5120",
 465             "addresses": "1"
 466          }
 467       }
 468
 469    **Example response**:
 470
 471    .. sourcecode:: http
 472
 473       HTTP/1.1 200 OK
 474       Content-Type: application/json
 475
 476       {
 477          "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
 478          "result": "ok",
 479          "message": "capacity decrease successful"
 480       }
 481
 482 Increase Capacity
 483 -----------------
 484
 485 Increase total capacity for the reservation system for a given time window.
 486
 487 Request parameters
 488
 489 ============================ =============== ==============================================
 490 Name                         Type            Description
 491 ============================ =============== ==============================================
 492 source                       String          Id of the resource container
 493 start                        DateTime        Start/end defines the time window when total
 494                                              capacity is increased
 495 end                          DateTime
 496 capacity.cores               int16           Increased amount of cores
 497 capacity.ram                 int32           Increased amount of RAM
 498 capacity.instances           int16           Increased amount of instances
 499 capacity.addresses           int32           Increased amount of public IP addresses
 500 ============================ =============== ==============================================
 501
 502 Response parameters
 503
 504 ============================ =========== ==============================================
 505 Name                         Type        Description
 506 ============================ =========== ==============================================
 507 pool-id                      String      Id of the resource pool
 508 result                       Enumeration Result info
 509 message                      String      Output message
 510 ============================ =========== ==============================================
 511
 512 .. http:post:: /increase-capacity
 513    :noindex:
 514
 515    **Example request**:
 516
 517    .. sourcecode:: http
 518
 519       POST /increase-capacity HTTP/1.1
 520       Accept: application/json
 521
 522       {
 523          "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f",
 524          "capacity": {
 525              "cores": "20",
 526              "ram": "51200",
 527              "instances": "10",
 528              "addresses": "10"
 529          }
 530       }
 531
 532    **Example response**:
 533
 534    .. sourcecode:: http
 535
 536       HTTP/1.1 200 OK
 537       Content-Type: application/json
 538
 539       {
 540          "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
 541          "result": "ok",
 542          "message": "capacity increase successful"
 543       }
 544
 545 Query Capacity
 546 --------------
 547
 548 Query for capacity information about a specified resource collection.
 549
 550 Request parameters
 551
 552 ============================ ================== ==============================================
 553 Name                         Type               Description
 554 ============================ ================== ==============================================
 555 capacity                     Enumeration        Return total or reserved or available or
 556                                                 usage capacity information
 557 zone                         String             Id to an availability zone
 558 show-utilization             Boolean            Show capacity utilization
 559 without                      ResourceCollection Excludes specified collection identifiers
 560                                                 from the result
 561 elements.some                ResourceElement    Query for ResourceCollection(s) that contain
 562                                                 some or more of these element(s)
 563 elements.every               ResourceElement    Query for ResourceCollection(s) that contain
 564                                                 all of these element(s)
 565 window.start                 DateTime           Matches entries that are within the specified
 566                                                 start/end window
 567 window.end                   DateTime
 568 window.scope                 Enumeration        Matches entries that start {and/or} end
 569                                                 within the time window
 570 ============================ ================== ==============================================
 571
 572 Response parameters
 573
 574 ============================ =================== ================================
 575 Name                         Type                Description
 576 ============================ =================== ================================
 577 collections                  ResourceCollection  List of matching collections
 578 utilization                  CapacityUtilization Capacity utilization over time
 579 ============================ =================== ================================
 580
 581 .. http:post:: /query-capacity
 582    :noindex:
 583
 584    **Example request**:
 585
 586    .. sourcecode:: http
 587
 588       POST /query-capacity HTTP/1.1
 589       Accept: application/json
 590
 591       {
 592         "show-utilization": false
 593       }
 594
 595    **Example response**:
 596
 597    .. sourcecode:: http
 598
 599       HTTP/1.1 201 CREATED
 600       Content-Type: application/json
 601
 602       {
 603         "collections": [
 604           "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
 605         ],
 606         "utilization": []
 607       }
 608