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 ============================ =============== ==============================================
 327
 328 Response parameters
 329
 330 ============================ =========== ==============================================
 331 Name                         Type        Description
 332 ============================ =========== ==============================================
 333 instance-id                  String      Id of the instance
 334 result                       Enumeration Result info
 335 message                      String      Output message
 336 ============================ =========== ==============================================
 337
 338 .. http:post:: /create-instance
 339    :noindex:
 340
 341    **Example request**:
 342
 343    .. sourcecode:: http
 344
 345       POST /create-instance HTTP/1.1
 346       Accept: application/json
 347
 348       {
 349         "provider-id": "f25ed9cb-de57-43d5-9b4a-a389a1397302",
 350         "name": "vm1",
 351         "image": "ddffc6f5-5c86-4126-b0fb-2c71678633f8",
 352         "flavor": "91bfdf57-863b-4b73-9d93-fc311894b902"
 353       }
 354
 355    **Example response**:
 356
 357    .. sourcecode:: http
 358
 359       HTTP/1.1 200 OK
 360       Content-Type: application/json
 361
 362       {
 363         "instance-id": "82572779-896b-493f-92f6-a63008868250",
 364         "result": "ok",
 365         "message": "created-instance request accepted"
 366       }
 367
 368 Destroy Instance
 369 ----------------
 370
 371 Destroy an instance of resource utilization and release it back to the pool.
 372
 373 Request parameters
 374
 375 ============================ =============== ==============================================
 376 Name                         Type            Description
 377 ============================ =============== ==============================================
 378 instance-id                  String          Id of the instance to be destroyed
 379 ============================ =============== ==============================================
 380
 381 Response parameters
 382
 383 ============================ =========== ==============================================
 384 Name                         Type        Description
 385 ============================ =========== ==============================================
 386 result                       Enumeration Result info
 387 message                      String      Output message
 388 ============================ =========== ==============================================
 389
 390 .. http:post:: /destroy-instance
 391    :noindex:
 392
 393    **Example request**:
 394
 395    .. sourcecode:: http
 396
 397       POST /destroy-instance HTTP/1.1
 398       Accept: application/json
 399
 400       {
 401          "instance-id": "82572779-896b-493f-92f6-a63008868250"
 402       }
 403
 404    **Example response**:
 405
 406    .. sourcecode:: http
 407
 408       HTTP/1.1 200 OK
 409       Content-Type: application/json
 410
 411       {
 412         "result": "ok",
 413         "message": "instance destroyed and resource released back to pool"
 414       }
 415
 416 Decrease Capacity
 417 -----------------
 418
 419 Decrease total capacity for the reservation system for a given time window.
 420
 421 Request parameters
 422
 423 ============================ =============== ==============================================
 424 Name                         Type            Description
 425 ============================ =============== ==============================================
 426 source                       String          Id of the resource container
 427 start                        DateTime        Start/end defines the time window when total
 428                                              capacity is decreased
 429 end                          DateTime
 430 capacity.cores               int16           Decreased amount of cores
 431 capacity.ram                 int32           Decreased amount of RAM
 432 capacity.instances           int16           Decreased amount of instances
 433 capacity.addresses           int32           Decreased amount of public IP addresses
 434 ============================ =============== ==============================================
 435
 436 Response parameters
 437
 438 ============================ =========== ==============================================
 439 Name                         Type        Description
 440 ============================ =========== ==============================================
 441 pool-id                      String      Id of the resource pool
 442 result                       Enumeration Result info
 443 message                      String      Output message
 444 ============================ =========== ==============================================
 445
 446 .. http:post:: /decrease-capacity
 447    :noindex:
 448
 449    **Example request**:
 450
 451    .. sourcecode:: http
 452
 453       POST /decrease-capacity HTTP/1.1
 454       Accept: application/json
 455
 456       {
 457          "source": "ResourcePool:4085f0da-8030-4252-a0ff-c6f93870eb5f",
 458          "capacity": {
 459             "cores": "3",
 460             "ram": "5120",
 461             "addresses": "1"
 462          }
 463       }
 464
 465    **Example response**:
 466
 467    .. sourcecode:: http
 468
 469       HTTP/1.1 200 OK
 470       Content-Type: application/json
 471
 472       {
 473          "pool-id": "c63b2a41-bcc6-42f6-8254-89d633e1bd0b",
 474          "result": "ok",
 475          "message": "capacity decrease successful"
 476       }
 477
 478 Increase Capacity
 479 -----------------
 480
 481 Increase total capacity for the reservation system for a given time window.
 482
 483 Request parameters
 484
 485 ============================ =============== ==============================================
 486 Name                         Type            Description
 487 ============================ =============== ==============================================
 488 source                       String          Id of the resource container
 489 start                        DateTime        Start/end defines the time window when total
 490                                              capacity is increased
 491 end                          DateTime
 492 capacity.cores               int16           Increased amount of cores
 493 capacity.ram                 int32           Increased amount of RAM
 494 capacity.instances           int16           Increased amount of instances
 495 capacity.addresses           int32           Increased amount of public IP addresses
 496 ============================ =============== ==============================================
 497
 498 Response parameters
 499
 500 ============================ =========== ==============================================
 501 Name                         Type        Description
 502 ============================ =========== ==============================================
 503 pool-id                      String      Id of the resource pool
 504 result                       Enumeration Result info
 505 message                      String      Output message
 506 ============================ =========== ==============================================
 507
 508 .. http:post:: /increase-capacity
 509    :noindex:
 510
 511    **Example request**:
 512
 513    .. sourcecode:: http
 514
 515       POST /increase-capacity HTTP/1.1
 516       Accept: application/json
 517
 518       {
 519          "source": "ResourceProvider:f6f13fe3-0126-4c6d-a84f-15f1ab685c4f",
 520          "capacity": {
 521              "cores": "20",
 522              "ram": "51200",
 523              "instances": "10",
 524              "addresses": "10"
 525          }
 526       }
 527
 528    **Example response**:
 529
 530    .. sourcecode:: http
 531
 532       HTTP/1.1 200 OK
 533       Content-Type: application/json
 534
 535       {
 536          "pool-id": "279217a4-7461-4176-bf9d-66770574ca6a",
 537          "result": "ok",
 538          "message": "capacity increase successful"
 539       }
 540
 541 Query Capacity
 542 --------------
 543
 544 Query for capacity information about a specified resource collection.
 545
 546 Request parameters
 547
 548 ============================ ================== ==============================================
 549 Name                         Type               Description
 550 ============================ ================== ==============================================
 551 capacity                     Enumeration        Return total or reserved or available or
 552                                                 usage capacity information
 553 zone                         String             Id to an availability zone
 554 show-utilization             Boolean            Show capacity utilization
 555 without                      ResourceCollection Excludes specified collection identifiers
 556                                                 from the result
 557 elements.some                ResourceElement    Query for ResourceCollection(s) that contain
 558                                                 some or more of these element(s)
 559 elements.every               ResourceElement    Query for ResourceCollection(s) that contain
 560                                                 all of these element(s)
 561 window.start                 DateTime           Matches entries that are within the specified
 562                                                 start/end window
 563 window.end                   DateTime
 564 window.scope                 Enumeration        Matches entries that start {and/or} end
 565                                                 within the time window
 566 ============================ ================== ==============================================
 567
 568 Response parameters
 569
 570 ============================ =================== ================================
 571 Name                         Type                Description
 572 ============================ =================== ================================
 573 collections                  ResourceCollection  List of matching collections
 574 utilization                  CapacityUtilization Capacity utilization over time
 575 ============================ =================== ================================
 576
 577 .. http:post:: /query-capacity
 578    :noindex:
 579
 580    **Example request**:
 581
 582    .. sourcecode:: http
 583
 584       POST /query-capacity HTTP/1.1
 585       Accept: application/json
 586
 587       {
 588         "show-utilization": false
 589       }
 590
 591    **Example response**:
 592
 593    .. sourcecode:: http
 594
 595       HTTP/1.1 201 CREATED
 596       Content-Type: application/json
 597
 598       {
 599         "collections": [
 600           "ResourcePool:279217a4-7461-4176-bf9d-66770574ca6a"
 601         ],
 602         "utilization": []
 603       }
 604