XPRESSO
- Welcome to XPRESSO!
- About XPRESSO
- Getting Started with XPRESSO
- Quick Start
- Setting up your Test Environment
- Defining your Lab Resources
- Job Creation, Execution & Test Results
- Tracking Events
- Integrating XPRESSO with other Tools and Services
- System Administrator Tasks
- Working with APIs
- Change Log
- Glossary
Request(s) and Bundle Requests REST APIs
About XPRESSO Request(s) and Bundle Requests REST APIs
XPRESSO provides public REST APIs to manage requests and retrieve request results.
XPRESSO provides the following public REST APIs to submit, retrieve, and stop Request(s) and Bundled Request information.
Submit Request
Submits an already defined XPRESSO request.
URL:
/api/v2/requestsMethod:
POSTPermission Required:
run_requestGroup: retrieved from
headersData Payload:
NOTE 1:
All fields other thanprofileare optional ways to override the defaults or otherwise customize your request.
NOTE 2:
Payload can either containtestbedsor atopologieslist. Providing both returns HTTP 400.
NOTE 3:
You can submit a group request with profiles from same group or different groups. Group requests with profiles belonging to different groups will be handled as Cross-Group Executions. All items will be sorted by groups and submitted either as a single run or a group run to its resource group (XPRESSO group that the profile(s) belongs to). The progress of all these runs can be monitored in the Aggregated Request Dashboard of the request group.
NOTE 4:
For Cross-Group Executions, permissions apply. You must have the right permission to submit requests to all item resource groups. Only the requests submitted to groups you have valid permission in, will be triggered.Submit a Single Request
jsonCopy
{ "profile": "1234-1234-1234-1234", "cdets": { "bugs": ["CSC1234"], "ddts_attribute": ["abc", "123"], "attach_report": true }, "bundle": "1234-1234-1234-1234", "branch": "feature-A", "label": "test feature A", "description": "This is my test run", "testbeds": ["1234-1234-1234-1234"], "topology": "1234-1234-1234-1234", "parameters":{ "job_args": { "--key": "value" }, "harness_args": { "-pyats_arg": "value" }, "env_vars": { "ENV_VAR": "value" } }, "clean": true, "images": ["file:///auto/something.bin", "https://my-server.mydomain.com/images/something-else.bin"], "max_request_runtime_seconds": 43200, "tags": ["tag1", "tag2"], "interest_list": ["myemail@mycompany.com"], "meta": { /* any valid json */ }, "schedule_id": "SCH0000017", "submitted_for": "username", "compare_baseline": true, "compare_id": "REQ0000023-1-run", "is_baseline": true, "category": "nightly", "source_string": "string value of request, this is auto generated by gateway middleware", "assigned_node": "my-jenkins-node-label" }Submit Group Requests (Comprising multiple profiles)
jsonCopy
{ "meta": { "label": "labelabc", "default_user": "username", "bugs": [], "ddts_attributes": [], "attach_report": false }, "submitted_for": "username", "branch": "userbranch", "max_request_runtime_seconds": 1234, "interest_list": [ "username@domain.com" ], "label": "labelabc", "description": "myreq", "call_stack": [ { "service_name": "cdets", "meta": { "label": "labelabc", "default_user": "username", "bugs": [], "ddts_attributes": [], "attach_report": false, "delay": true }, "item_states": [ "TERMINAL" ] } ], "tags": [], "schedule_id": "", "items": [ { "profile": "1234-1234-1234-1234", "harness_args": { }, "clean": false, "run": true, "testbeds": [], "qmgr": {}, "bugs": [], "labels": [ "mylabel" ], "reservations": [], "parameters": { "env_vars": { }, "job_args": { } }, "topology": "" }, { "profile": "5678-5678-5678-5678", "harness_args": { }, "clean": false, "run": true, "testbeds": [], "parameters": { "env_vars": { }, "job_args": { } }, "topology": "" }, { "profile": "9101-9101-9101-9101", "harness_args": { }, "clean": false, "run": true, "testbeds": [], "parameters": { "env_vars": { }, "job_args": { } }, "topology": "" } ] }
Submit Manifest Requests (Based off pyATS Docker Image Manifest)
- items is optional, if not provided, will run all manifest profiles discovered
jsonCopy
{ "manifest": true, "docker_image": "78d92717-283b-4ba7-9a44-445067fd2a98", # support url syntax: dockerhub.cisco.com/ngdvex-taas/group/polaris-sdk:<LABEL> "submitted_for": "dwapstra", "branch": "N/A", "max_request_runtime_seconds": 600, "interest_list": [ "dwapstra@cisco.com" ], "items": [ { "profile": "DEFAULT", "priority": 4, "run": true, "clean": true, "file": "/pyats/examples/basic/basic_example_job.tem", "parameters": { "env_vars": { "IMAGE": "/path/to/image" }, # if user uses IMAGE env var in the clean.yaml "job_args": { "--clean-platform-image": "cat9k:/path/to/image" } # cat9k devices will use the new image } } ] }Success Response - Same Group
Condition: Data provided is valid and User is Authenticated
Code:
200 OKResponse example:
jsonCopy
{ "username": "some_user", "request_id": "REQ0000426", "state": "PREPARING", "branch": "N/A", "submitter": "my_cec", "request_url": "http://xpresso-server/services/request-detail/REQ0000426", "service_url": "http://xpresso-server/services/request-detail/REQ0000426?share_key=b76a91b2-635a-41ad-89f0-4d07768a5d9d", "items": ["REQ0000426-1"] }
Success Response - Cross Group
Condition: Data provided is valid and User is Authenticated
Code:
200 OKResponse example:
jsonCopy
{ "aggregator_id": "AGG0000001", "state": "RUNNING", "detail_link": "https://xpresso-dev-1.cisco.com/api/v1/aggregator/AGG0000001", "uuid": "uuid11-cccc-aaaa-bbbb-uuid222", "created_by": "my_cec", "date_created": "2021-01-22T20:24:14.227246Z", <!-- requests could be empty right after submission --> "requests": [ { "request_id": "REQ0000001", "resource_group": "Group A", "error": null, "description": "my joined req", "branch": "mybranch", "id": 1, "created_by": "my_cec", "uuid": "uuid11-cccc-aaaa-bbbb-uuid222", "deleted_at": null, "schedule_id": null, "submitter": "my_cec", "name": "Request1", "state": "RUNNING", "date_created": "2021-01-22T20:24:16.146453Z", "aggregated_request_id": 1 }, { "request_id": "REQ0000002", "resource_group": "Group B", "error": null, "description": "my joined req", "branch": "mybranch", "id": 2, "created_by": "my_cec", "uuid": "uuid11-cccc-aaaa-bbbb-uuid222", "deleted_at": null, "schedule_id": null, "submitter": "my_cec", "name": "basic_Example...", "state": "ERRORED", "date_created": "2021-01-22T20:24:18.248926Z", "aggregated_request_id": 1 } ] }
Error Response
- Condition: If provided data is invalid, eg. profile not found
- Code:
400 BAD REQUEST - Response example:json
Copy
{ "Error": "Provided profile is not defined." }
Submit Replay Requests
Based off item id to re-run previous request
URL:
/api/v2/requests/:request_id/replayMethod:
POSTPermission Required:
run_requestGroup: retrieved from
headersData Payload:
All keys are optional. Providing nothing will re-run the request exactly as it was originally. Any provided info in the body overrides the original request.
jsonCopy
{ "interest_list": ["example@cisco.com"], // who to email the report to "submitted_for": "username", // user the submissions is on behalf of "items": [ // config per item { "item_id": "REQ0008034-1", "priority": 3, // change item priority "parameters": { // override or add additional args and ENV vars "env_vars":{ "key": "value"}, "job_args": { "key": "value" }, "harness_args": { "key": "value" } }, "testcases": { // replay specific testcases "uids": "string", // standard pyATS "trigger_uids": "string", // genie triggers "verification_uids":"string" // genie verifications }, // NOTE: testbed and topology and mutually exclusive "testbed": "Nexus-2", // change which testbed is used "topology": "CSR-1000v-2node", // change which topology is used "clean": true, // force to run or not run clean "run": true, // for to run or not run a job "images": { // override images when running clean "device": { "N93_4": [ "URL_TO_IMAGE_ONE", "URL_TO_IMAGE_TWO" ] }, "os": { "OS_NAME": [ "URL_TO_IMAGE" ] }, "group": { "GROUP_NAME": [ "URL_TO_IMAGE" ] }, "platform": { "PLATFORM_NAME": [ "URL_TO_IMAGE" ] } } } ] }Success Response
- Condition: Data provided is valid and User is Authenticated
- Code:
200 OK - Response example:json
Copy
{ "username": "some_user", "request_id": "REQ0000426", "state": "PREPARING", "branch": "N/A", "submitter": "my_cec", "request_url": "http://xpresso-server/services/request-detail/REQ0000426", "service_url": "http://xpresso-server/services/request-detail/REQ0000426?share_key=b76a91b2-635a-41ad-89f0-4d07768a5d9d", "items": ["REQ0000426-1"] }
Retrieve Requests
Returns requests defined under group.
- URL:
/api/v2/requests - Method:
GET - Permission Required: No permission required.
- Group: retrieved from
headers - Success Response
- Condition: Authorized User.
- Code:
200 OK - Response example:json
Copy
[ { "source": "schedule", "username": "user", "item_ids": [ "REQ0007931-1", "REQ0007931-2", "REQ0007931-3" ], "postback_token": "***************", "comparison_summary": [ { "failure_reason": null, "run_id": "REQ0007931-2", "comparison_count": { "added": 0, "fixed": 0, "ignored": 0, "broken": 0, "same": 0, "mismatched": 0, "missing": 0 }, "verdict": "Matched or Improved", "baseline_id": "REQ0007669-1", "comparison_details": {} } ], "consolidated_summary": { "fail": 0, "unknown": 0, "applicable_tasks": 0, "success_rate_rule": "('passed' + 'passx' + 'skip')/total_tasks * 100.0", "block": 0, "abort": 0, "skip": 0, "total_tasks": 0, "passx": 0, "pass": 0, "error": 0, "success_rate": 0 }, "completion_time": null, "verdict": "matched or improved", "meta": { "is_baseline": true, "compare_baseline": true, "label": "bundlelabeldaily", "_email": { "is_baseline": "Baseline", "compare_baseline": "Generate Baseline Comparison", "label": "label", "requestType": "requestType", "conditional_baseline": "Conditional Baseline", "default_user": "Fallback User ID for CDETS Attachment", "bugs": "CDET ID(s)", "ddts_attributes": "CDETS Attribute(s)", "attach_report": "Attach Result Enclosure", "compare_id": "Compare to Baseline" }, "requestType": "schedule", "conditional_baseline": false, "default_user": "user", "bugs": [ "CSC123456" ], "ddts_attributes": [ "buga" ], "attach_report": true, "compare_id": null }, "state": "ERRORED", "children": [], "schedule_id": "SCHED0000073", "name": "some_bundle", "parent_request": null, "request_url": "https://xpresso-server/services/request-detail/REQ0007931", "date_created": "2020-07-24T16:00:02.245195Z", "has_baseline": false, "detail_link": "https://xpresso-server/api/v2/requests/REQ0007931", "description": "run this bundle daily for the rest of July", "branch": "xpresso", "max_request_runtime_seconds": 900, "instance_id": "xpresso-dev", "baseline_requested": true, "submitter": "user", "items": [ { "is_baseline": false, "job": { "id": "a7f29e3c-3978-4dc8-bfe3-8302d1c67be8", "path": "/sample/example.py", "name": "associatedToLaaS" }, "submitted_testbeds": [], "engine": { "id": "92702bba-2313-4afc-8fbc-c476e276b602", "name": "jenkins", "type": "jenkins" }, "max_clean_runtime_seconds": 240, "id": "REQ0007931-1", "options": { "-liveview_callback_url": "https://xpresso-server/api/v2/jenkins/liveviews", "-liveview_callback_token": "*****************", "-liveview_host": "0.0.0.0", "-liveview": true }, "start_time": null, "max_runtime_seconds": 240, "results": { "clean": { "summary": {}, "results_compare": {}, "results_baseline": {}, "results_meta": {}, "start_time": null, "state": null, "uid": null, "completion_time": null }, "run": { "summary": { "unknown": 0, "block": 0, "abort": 0, "skip": 0, "total_tasks": 0, "fail": 0, "passx": 0, "pass": 0, "success_rate": 0, "error": 0, "applicable_tasks": 0 }, "results_compare": {}, "results_baseline": {}, "results_meta": {}, "start_time": null, "state": "NOTRUN", "uid": "REQ0007931-1-run", "completion_time": null } }, "reservations": [], "profile": { "id": "356f2dac-a903-441f-9627-abbefd882970", "name": "DEFAULT" }, "selected_testbed": {}, "topology": { "id": "67bfc5a9-348a-4b77-94df-c729a781e644", "plugin_config": {}, "reservation_name": null, "keepalive": false, "postprocflag": null, "group": "Test", "topology": "67bfc5a9-348a-4b77-94df-c729a781e644", "clean_details": [], "clean_override": {}, "name": "omy_topology", "is_virtual": false, "backend": "laas", "duration": 0 }, "env": {}, "meta": { "is_baseline": true, "label": "bundlelabeldaily", "attach_report": true, "requestType": "schedule", "conditional_baseline": false, "default_user": "user", "compare_baseline": true, "bugs": [ "CSCt123456" ], "ddts_attributes": [ "buga" ], "release_laas": true, "compare_id": null }, "priority": 4, "state": "ERRORED", "completion_time": "2020-07-24T16:00:14.216335Z" } ], "interest_list": [ yser@company.com ], "id": "REQ0007931", "instance_url": "https://xpresso-server/" } ]
Retrieve Request
Returns request information including result information.
URL:
/api/v2/requests/:idMethod:
GETPermission Required: No permission required. User needs to be a member of the group that owns the request.
Group: retrieved from
headersSuccess Response
- Condition: If request exists and Authorized User is a member of the group.
- Code:
200 OK - Response example:json
Copy
{ "source": "API", "items_queue_order": false, "username": "user", "name": "Request_Name", "call_stack": "[{'meta': {'bugs': ['CSC1234'], 'delay': True, 'attach_report': True}, 'service_name': 'cdets', 'item_states': ['TERMINAL']}]", "postback_token": "****************", "date_completed": "2020-07-21T22:43:41.737960Z", "detail_link": "https://xpresso-server/api/v2/requests/REQ0007928", "consolidated_summary": { "fail": 0, "unknown": 0, "applicable_tasks": 0, "success_rate_rule": "('passed' + 'passx' + 'skip')/total_tasks * 100.0", "block": 0, "abort": 0, "skip": 0, "total_tasks": 0, "passx": 0, "pass": 0, "error": 0, "success_rate": 0 }, "verdict": null, "service_url": "https://xpresso-server/services/request-detail/REQ0007928?share_key=63870b7e-9a55-420a-9d5c-25e6db48ecdd", "meta": { "bugs": [ "CSC1234" ], "attach_report": true, "_email": { "schedule_id": "schedule_id", "attach_report": "Attach Result Enclosure", "ddts_attributes": "CDETS Attribute(s)", "label": "label", "bugs": "CDET ID(s)" } }, "state": "FAILED", "children": [], "schedule_id": null, "rerun_root": "REQ0007928", "parent_request": null, "request_url": "https://xpresso-server/services/request-detail/REQ0007928", "requeue": false, "date_created": "2020-07-21T22:41:45.488849Z", "has_baseline": false, "description": "This is a test", "branch": "xpresso", "comparison_summary": [], "max_request_runtime_seconds": 43200, "instance_id": "xpresso-dev", "baseline_requested": false, "submitter": "user", "items": [ { "compare_to": "REQ0007927-1-run", "priority_history": [], "parent": null, "id": "REQ0007928-1", "assigned_node": null, "stop_requested": {}, "error_detail": null, "children": [], "external_meta": {}, "is_baseline": false, "baseline_manually_modified": false, "cloud_payload": {}, "selected_reservation": null, "harness_instances": [ { "config": "", "path": "/my_env/pyatsDev3.6", "deleted": false, "name": "TestHarness", "config_state": "MAINTENANCE", "support_liveview": false, "harness": { "clean": "kleenex", "name": "pyATS", "run": "easypy" }, "site": "SJC", "id": "38eb1399-e20d-4d4c-9a78-b470ba2ad9ff", "oper_state": "ONLINE", "bldg": "ALL" } ], "submitted_testbeds": [ { "reservations": [], "id": "b0978142-269b-41c0-a03a-85afaa02e6f8", "name": "Testbed-1" }, { "reservations": [], "id": "745d0494-3ef1-4670-8f0f-7691107577e0", "name": "Testbed-2" } ], "copy_on_testbeds": false, "job": { "id": "df936b96-410b-4679-8750-a6de28f8e231", "path": "/path/to/my/job/my_job.py", "name": "My_Job" }, "results": { "clean": { "summary": {}, "results_compare": {}, "results_baseline": {}, "scripts": [], "results_meta": {}, "start_time": null, "state": null, "uid": null, "completion_time": null }, "run": { "summary": { "unknown": 0, "block": 0, "abort": 0, "skip": 0, "total_tasks": 0, "fail": 0, "passx": 0, "pass": 0, "success_rate": 0, "error": 0, "applicable_tasks": 0 }, "results_compare": {}, "results_baseline": {}, "scripts": [], "results_meta": { "date_created": "2020-07-21T22:43:21.686842Z", "run_time": "5.0", "branch": "N/A", "created_by": "", "stop_time": "2020-07-21T15:44:01Z", "exec_host": "my-exec-server", "component": "N/A", "job": "My_Job", "start_time": "2020-07-21T15:43:55Z", "result_format": "yaml", "suite_name": "My_Job", "testbed": "Testbed-1", "status": "completed", "submitter": "user", "ats_tree": "/my_env/pyatsDev3.6", "related_id": "REQ0007928-1", "meta_info": { "trade_link": "http://link-to-trade/myarchive-bbf493-58.2020Jul21_15:44:07.000861.zip" }, "id": "REQ0007928-1-run", "archive_location": "/s3/archives/zipped/2020/7/21/REQ0007928-1-run.zip", "last_accessed": "2020-07-21T22:43:21.970643Z" }, "start_time": "2020-07-21T22:42:53.965584Z", "state": "FAILED", "id": "REQ0007928-1-run", "completion_time": "2020-07-21T22:43:38.952964Z" } }, "pre_post_plugins": {}, "call_stack_report": [ { "end_time": null, "description": "optional", "callback_url": null, "start_time": null, "service_name": "cdets", "retry_count": 0, "return_code": 0, "item_state": "TERMINAL", "meta": { "bugs": [ "CSC1234" ], "attach_report": true, "delay": true }, "detail": null, "state": "INIT", "headers": {} } ], "max_runtime_seconds": 43200, "priority": 4, "category": "[]", "id": "REQ0007928", "run_id": "REQ0007928-1-run", "clean_id": null, "engine": { "id": "92702bba-2313-4afc-8fbc-c476e276b602", "name": "jenkins", "type": "jenkins" }, "options": { "-cov_devices": "N95_2", "-liveview_callback_url": "https://xpresso-server/api/v2/jenkins/liveviews", "-liveview_callback_token": "***************", "-liveview": true, "-cov_dest": "/coverage_dir/temp/", "-liveview_host": "0.0.0.0", "-cov_upload_platform": "n9000" }, "profile": { "id": "23c1cc46-ce67-4a3d-b715-2aa57abbf493", "name": "DEFAULT" }, "selected_testbed": { "id": "b0978142-269b-41c0-a03a-85afaa02e6f8", "name": "Testbed-1" }, "env": {}, "meta": {}, "state": "FAILED", "labels": [], "harness_config": [ { "easypy": "" } ], "bugs": [], "start_time": "2020-07-21T22:42:53.974350Z", "reservations": [], "max_clean_runtime_seconds": 43200, "rerun_root": null, "completion_time": "2020-07-21T22:43:40.181730Z", "topology": {} } ], "interest_list": [ "user@mycompany.com" ], "id": "REQ0007928", "instance_url": "https://xpresso-server/", "tags": [] }
Error Response
- Condition: If request does not exist with provided
request_id - Code:
404 NOT FOUND - Response example:
{}
- Condition: If request does not exist with provided
Stop Request
Terminates an already submitted request.
URL:
/api/v2/requests/:id/stopMethod:
PATCHPermission Required:
stop_requestGroup: retrieved from
headersData Payload
jsonCopy
{ "reason": "Resource urgently needed for another request" }Success Response
- Condition: If request exists and in
RUNNINGstate and Authorized User has permission to stop request. - Code:
200 OK - Response example:json
Copy
{ "state": "STOPPED", "branch": "N/A", "request_url": "http://xpresso-server/services/request-detail/REQ0000427", "id": "REQ0000427", "username": "user", "service_url": "http://xpresso-server/services/request-detail/REQ0000427?share_key=9e8fa6f5-b968-4fa5-8c93-29acb78293c6", "submitter": "user2", "items": ["REQ0000427-1"] }
- Condition: If request exists and in
Error Response
- Condition: If request does not exist with provided
request_id - Code:
404 NOT FOUND - Response example:
{}
- Condition: If request does not exist with provided