docs/requirements/supported_apis.rst

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