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