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