docs/testing/user/userguide/08-api.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) OPNFV, Huawei Technologies Co.,Ltd and others.
   5
   6 Yardstick Restful API
   7 ======================
   8
   9
  10 Abstract
  11 --------
  12
  13 Yardstick support restful API since Danube.
  14
  15
  16 Available API
  17 -------------
  18
  19 /yardstick/env/action
  20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  21
  22 Description: This API is used to prepare Yardstick test environment. For Euphrates, it supports:
  23
  24 1. Prepare yardstick test environment, including set external network environment variable, load Yardstick VM images and create flavors;
  25 2. Start an InfluxDB Docker container and config Yardstick output to InfluxDB;
  26 3. Start a Grafana Docker container and config it with the InfluxDB.
  27
  28 Which API to call will depend on the parameters.
  29
  30
  31 Method: POST
  32
  33
  34 Prepare Yardstick test environment
  35 Example::
  36
  37     {
  38         'action': 'prepare_env'
  39     }
  40
  41 This is an asynchronous API. You need to call /yardstick/asynctask API to get the task result.
  42
  43
  44 Start and config an InfluxDB docker container
  45 Example::
  46
  47     {
  48         'action': 'create_influxdb'
  49     }
  50
  51 This is an asynchronous API. You need to call /yardstick/asynctask API to get the task result.
  52
  53
  54 Start and config a Grafana docker container
  55 Example::
  56
  57     {
  58         'action': 'create_grafana'
  59     }
  60
  61 This is an asynchronous API. You need to call /yardstick/asynctask API to get the task result.
  62
  63
  64 /yardstick/asynctask
  65 ^^^^^^^^^^^^^^^^^^^^
  66
  67 Description: This API is used to get the status of asynchronous tasks
  68
  69
  70 Method: GET
  71
  72
  73 Get the status of asynchronous tasks
  74 Example::
  75
  76     http://<SERVER IP>:<PORT>/yardstick/asynctask?task_id=3f3f5e03-972a-4847-a5f8-154f1b31db8c
  77
  78 The returned status will be 0(running), 1(finished) and 2(failed).
  79
  80 NOTE::
  81
  82     <SERVER IP>: The ip of the host where you start your yardstick container
  83     <PORT>: The outside port of port mapping which set when you start start yardstick container
  84
  85
  86 /yardstick/testcases
  87 ^^^^^^^^^^^^^^^^^^^^
  88
  89 Description: This API is used to list all released Yardstick test cases.
  90
  91
  92 Method: GET
  93
  94
  95 Get a list of released test cases
  96 Example::
  97
  98     http://<SERVER IP>:<PORT>/yardstick/testcases
  99
 100
 101 /yardstick/testcases/release/action
 102 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 103
 104 Description: This API is used to run a Yardstick released test case.
 105
 106
 107 Method: POST
 108
 109
 110 Run a released test case
 111 Example::
 112
 113     {
 114         'action': 'run_test_case',
 115         'args': {
 116             'opts': {},
 117             'testcase': 'opnfv_yardstick_tc002'
 118         }
 119     }
 120
 121 This is an asynchronous API. You need to call /yardstick/results to get the result.
 122
 123
 124 /yardstick/testcases/samples/action
 125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 126
 127 Description: This API is used to run a Yardstick sample test case.
 128
 129
 130 Method: POST
 131
 132
 133 Run a sample test case
 134 Example::
 135
 136     {
 137         'action': 'run_test_case',
 138         'args': {
 139             'opts': {},
 140             'testcase': 'ping'
 141         }
 142     }
 143
 144 This is an asynchronous API. You need to call /yardstick/results to get the result.
 145
 146
 147 /yardstick/testcases/<testcase_name>/docs
 148 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 149
 150 Description: This API is used to the documentation of a certain released test case.
 151
 152
 153 Method: GET
 154
 155
 156 Get the documentation of a certain test case
 157 Example::
 158
 159     http://<SERVER IP>:<PORT>/yardstick/taskcases/opnfv_yardstick_tc002/docs
 160
 161
 162 /yardstick/testsuites/action
 163 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 164
 165 Description: This API is used to run a Yardstick test suite.
 166
 167
 168 Method: POST
 169
 170
 171 Run a test suite
 172 Example::
 173
 174     {
 175         'action': 'run_test_suite',
 176         'args': {
 177             'opts': {},
 178             'testsuite': 'opnfv_smoke'
 179         }
 180     }
 181
 182 This is an asynchronous API. You need to call /yardstick/results to get the result.
 183
 184
 185 /yardstick/tasks/<task_id>/log
 186 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 187
 188 Description: This API is used to get the real time log of test case execution.
 189
 190
 191 Method: GET
 192
 193
 194 Get real time of test case execution
 195 Example::
 196
 197     http://<SERVER IP>:<PORT>/yardstick/tasks/14795be8-f144-4f54-81ce-43f4e3eab33f/log?index=0
 198
 199
 200 /yardstick/results
 201 ^^^^^^^^^^^^^^^^^^
 202
 203 Description: This API is used to get the test results of tasks. If you call /yardstick/testcases/samples/action API, it will return a task id. You can use the returned task id to get the results by using this API.
 204
 205
 206 Method: GET
 207
 208
 209 Get test results of one task
 210 Example::
 211
 212     http://<SERVER IP>:<PORT>/yardstick/results?task_id=3f3f5e03-972a-4847-a5f8-154f1b31db8c
 213
 214 This API will return a list of test case result
 215
 216
 217 /api/v2/yardstick/openrcs
 218 ^^^^^^^^^^^^^^^^^^^^^^^^^
 219
 220 Description: This API provides functionality of handling OpenStack credential file (openrc). For Euphrates, it supports:
 221
 222 1. Upload an openrc file for an OpenStack environment;
 223 2. Update an openrc;
 224 3. Get openrc file information;
 225 4. Delete an openrc file.
 226
 227 Which API to call will depend on the parameters.
 228
 229
 230 METHOD: POST
 231
 232
 233 Upload an openrc file for an OpenStack environment
 234 Example::
 235
 236     {
 237         'action': 'upload_openrc',
 238         'args': {
 239             'file': file,
 240             'environment_id': environment_id
 241         }
 242     }
 243
 244
 245 METHOD: POST
 246
 247
 248 Update an openrc file
 249 Example::
 250
 251     {
 252         'action': 'update_openrc',
 253         'args': {
 254             'openrc': {
 255                 "EXTERNAL_NETWORK": "ext-net",
 256                 "OS_AUTH_URL": "http://192.168.23.51:5000/v3",
 257                 "OS_IDENTITY_API_VERSION": "3",
 258                 "OS_IMAGE_API_VERSION": "2",
 259                 "OS_PASSWORD": "console",
 260                 "OS_PROJECT_DOMAIN_NAME": "default",
 261                 "OS_PROJECT_NAME": "admin",
 262                 "OS_USERNAME": "admin",
 263                 "OS_USER_DOMAIN_NAME": "default"
 264             },
 265             'environment_id': environment_id
 266         }
 267     }
 268
 269
 270 /api/v2/yardstick/openrcs/<openrc_id>
 271 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 272
 273 Description: This API provides functionality of handling OpenStack credential file (openrc). For Euphrates, it supports:
 274
 275 1. Get openrc file information;
 276 2. Delete an openrc file.
 277
 278
 279 METHOD: GET
 280
 281 Get openrc file information
 282 Example::
 283
 284     http://<SERVER IP>:<PORT>/api/v2/yardstick/openrcs/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 285
 286
 287 METHOD: DELETE
 288
 289
 290 Delete openrc file
 291 Example::
 292
 293     http://<SERVER IP>:<PORT>/api/v2/yardstick/openrcs/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 294
 295
 296 /api/v2/yardstick/pods
 297 ^^^^^^^^^^^^^^^^^^^^^^
 298
 299 Description: This API provides functionality of handling Yardstick pod file (pod.yaml). For Euphrates, it supports:
 300
 301 1. Upload a pod file;
 302
 303 Which API to call will depend on the parameters.
 304
 305
 306 METHOD: POST
 307
 308
 309 Upload a pod.yaml file
 310 Example::
 311
 312     {
 313         'action': 'upload_pod_file',
 314         'args': {
 315             'file': file,
 316             'environment_id': environment_id
 317         }
 318     }
 319
 320
 321 /api/v2/yardstick/pods/<pod_id>
 322 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 323
 324 Description: This API provides functionality of handling Yardstick pod file (pod.yaml). For Euphrates, it supports:
 325
 326 1. Get pod file information;
 327 2. Delete an openrc file.
 328
 329 METHOD: GET
 330
 331 Get pod file information
 332 Example::
 333
 334     http://<SERVER IP>:<PORT>/api/v2/yardstick/pods/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 335
 336
 337 METHOD: DELETE
 338
 339 Delete openrc file
 340 Example::
 341
 342     http://<SERVER IP>:<PORT>/api/v2/yardstick/pods/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 343
 344
 345 /api/v2/yardstick/images
 346 ^^^^^^^^^^^^^^^^^^^^^^^^
 347
 348 Description: This API is used to do some work related to Yardstick VM images. For Euphrates, it supports:
 349
 350 1. Load Yardstick VM images;
 351
 352 Which API to call will depend on the parameters.
 353
 354
 355 METHOD: POST
 356
 357
 358 Load VM images
 359 Example::
 360
 361     {
 362         'action': 'load_image',
 363         'args': {
 364             'name': 'yardstick-image'
 365         }
 366     }
 367
 368
 369 /api/v2/yardstick/images/<image_id>
 370 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 371
 372 Description: This API is used to do some work related to Yardstick VM images. For Euphrates, it supports:
 373
 374 1. Get image's information;
 375 2. Delete images
 376
 377 METHOD: GET
 378
 379 Get image information
 380 Example::
 381
 382     http://<SERVER IP>:<PORT>/api/v2/yardstick/images/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 383
 384
 385 METHOD: DELETE
 386
 387 Delete images
 388 Example::
 389
 390     http://<SERVER IP>:<PORT>/api/v2/yardstick/images/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 391
 392
 393 /api/v2/yardstick/tasks
 394 ^^^^^^^^^^^^^^^^^^^^^^^
 395
 396 Description: This API is used to do some work related to yardstick tasks. For Euphrates, it supports:
 397
 398 1. Create a Yardstick task;
 399
 400 Which API to call will depend on the parameters.
 401
 402
 403 METHOD: POST
 404
 405
 406 Create a Yardstick task
 407 Example::
 408
 409     {
 410         'action': 'create_task',
 411             'args': {
 412                 'name': 'task1',
 413                 'project_id': project_id
 414             }
 415     }
 416
 417
 418 /api/v2/yardstick/tasks/<task_id>
 419 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 420
 421 Description: This API is used to do some work related to yardstick tasks. For Euphrates, it supports:
 422
 423 1. Add a environment to a task
 424 2. Add a test case to a task;
 425 3. Add a test suite to a task;
 426 4. run a Yardstick task;
 427 5. Get a tasks' information;
 428 6. Delete a task.
 429
 430
 431 METHOD: PUT
 432
 433 Add a environment to a task
 434
 435 Example::
 436
 437     {
 438         'action': 'add_environment',
 439         'args': {
 440             'environment_id': 'e3cadbbb-0419-4fed-96f1-a232daa0422a'
 441         }
 442     }
 443
 444
 445 METHOD: PUT
 446
 447 Add a test case to a task
 448 Example::
 449
 450     {
 451         'action': 'add_case',
 452         'args': {
 453             'case_name': 'opnfv_yardstick_tc002',
 454             'case_content': case_content
 455         }
 456     }
 457
 458
 459
 460 METHOD: PUT
 461
 462 Add a test suite to a task
 463 Example::
 464
 465     {
 466         'action': 'add_suite',
 467         'args': {
 468             'suite_name': 'opnfv_smoke',
 469             'suite_content': suite_content
 470         }
 471     }
 472
 473
 474 METHOD: PUT
 475
 476 Run a task
 477
 478 Example::
 479
 480     {
 481         'action': 'run'
 482     }
 483
 484
 485
 486 METHOD: GET
 487
 488 Get a task's information
 489 Example::
 490
 491     http://<SERVER IP>:<PORT>/api/v2/yardstick/tasks/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 492
 493
 494 METHOD: DELETE
 495
 496 Delete a task
 497
 498 Example::
 499     http://<SERVER IP>:<PORT>/api/v2/yardstick/tasks/5g6g3e02-155a-4847-a5f8-154f1b31db8c
 500
 501
 502 /api/v2/yardstick/testcases
 503 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 504
 505 Description: This API is used to do some work related to yardstick testcases. For Euphrates, it supports:
 506
 507 1. Upload a test case;
 508 2. Get all released test cases' information;
 509
 510 Which API to call will depend on the parameters.
 511
 512
 513 METHOD: POST
 514
 515
 516 Upload a test case
 517 Example::
 518
 519     {
 520         'action': 'upload_case',
 521         'args': {
 522             'file': file
 523         }
 524     }
 525
 526
 527 METHOD: GET
 528
 529
 530 Get all released test cases' information
 531 Example::
 532
 533     http://<SERVER IP>:<PORT>/api/v2/yardstick/testcases
 534
 535
 536 /api/v2/yardstick/testcases/<case_name>
 537 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 538
 539 Description: This API is used to do some work related to yardstick testcases. For Euphrates, it supports:
 540
 541 1. Get certain released test case's information;
 542 2. Delete a test case.
 543
 544 METHOD: GET
 545
 546
 547 Get certain released test case's information
 548 Example::
 549
 550     http://<SERVER IP>:<PORT>/api/v2/yardstick/testcases/opnfv_yardstick_tc002
 551
 552
 553 METHOD: DELETE
 554
 555
 556 Delete a certain test case
 557 Example::
 558     http://<SERVER IP>:<PORT>/api/v2/yardstick/testcases/opnfv_yardstick_tc002
 559
 560
 561 /api/v2/yardstick/testsuites
 562 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 563
 564 Description: This API is used to do some work related to yardstick test suites. For Euphrates, it supports:
 565
 566 1. Create a test suite;
 567 2. Get all test suites;
 568
 569 Which API to call will depend on the parameters.
 570
 571
 572 METHOD: POST
 573
 574
 575 Create a test suite
 576 Example::
 577
 578     {
 579         'action': 'create_suite',
 580         'args': {
 581             'name': <suite_name>,
 582             'testcases': [
 583                 'opnfv_yardstick_tc002'
 584             ]
 585         }
 586     }
 587
 588
 589 METHOD: GET
 590
 591
 592 Get all test suite
 593 Example::
 594
 595     http://<SERVER IP>:<PORT>/api/v2/yardstick/testsuites
 596
 597
 598 /api/v2/yardstick/testsuites
 599 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 600
 601 Description: This API is used to do some work related to yardstick test suites. For Euphrates, it supports:
 602
 603 1. Get certain test suite's information;
 604 2. Delete a test case.
 605
 606 METHOD: GET
 607
 608
 609 Get certain test suite's information
 610 Example::
 611
 612     http://<SERVER IP>:<PORT>/api/v2/yardstick/testsuites/<suite_name>
 613
 614
 615 METHOD: DELETE
 616
 617
 618 Delete a certain test suite
 619 Example::
 620
 621     http://<SERVER IP>:<PORT>/api/v2/yardstick/testsuites/<suite_name>
 622
 623
 624 /api/v2/yardstick/projects
 625 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 626
 627 Description: This API is used to do some work related to yardstick test projects. For Euphrates, it supports:
 628
 629 1. Create a Yardstick project;
 630 2. Get all projects;
 631
 632 Which API to call will depend on the parameters.
 633
 634
 635 METHOD: POST
 636
 637
 638 Create a Yardstick project
 639 Example::
 640
 641     {
 642         'action': 'create_project',
 643         'args': {
 644             'name': 'project1'
 645         }
 646     }
 647
 648
 649 METHOD: GET
 650
 651
 652 Get all projects' information
 653 Example::
 654
 655     http://<SERVER IP>:<PORT>/api/v2/yardstick/projects
 656
 657
 658 /api/v2/yardstick/projects
 659 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 660
 661 Description: This API is used to do some work related to yardstick test projects. For Euphrates, it supports:
 662
 663 1. Get certain project's information;
 664 2. Delete a project.
 665
 666 METHOD: GET
 667
 668
 669 Get certain project's information
 670 Example::
 671
 672     http://<SERVER IP>:<PORT>/api/v2/yardstick/projects/<project_id>
 673
 674
 675 METHOD: DELETE
 676
 677
 678 Delete a certain project
 679 Example::
 680
 681     http://<SERVER IP>:<PORT>/api/v2/yardstick/projects/<project_id>
 682
 683
 684 /api/v2/yardstick/containers
 685 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 686
 687 Description: This API is used to do some work related to Docker containers. For Euphrates, it supports:
 688
 689 1. Create a Grafana Docker container;
 690 2. Create an InfluxDB Docker container;
 691
 692 Which API to call will depend on the parameters.
 693
 694
 695 METHOD: POST
 696
 697
 698 Create a Grafana Docker container
 699 Example::
 700
 701     {
 702         'action': 'create_grafana',
 703         'args': {
 704             'environment_id': <environment_id>
 705         }
 706     }
 707
 708
 709 METHOD: POST
 710
 711
 712 Create an InfluxDB Docker container
 713 Example::
 714
 715     {
 716         'action': 'create_influxdb',
 717         'args': {
 718             'environment_id': <environment_id>
 719         }
 720     }
 721
 722
 723 /api/v2/yardstick/containers/<container_id>
 724 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 725
 726 Description: This API is used to do some work related to Docker containers. For Euphrates, it supports:
 727
 728 1. Get certain container's information;
 729 2. Delete a container.
 730
 731 METHOD: GET
 732
 733
 734 Get certain container's information
 735 Example::
 736
 737     http://<SERVER IP>:<PORT>/api/v2/yardstick/containers/<container_id>
 738
 739
 740 METHOD: DELETE
 741
 742
 743 Delete a certain container
 744 Example::
 745
 746     http://<SERVER IP>:<PORT>/api/v2/yardstick/containers/<container_id>