Automation and testing

Create and control a lab through REST

Upload data.xml as raw bytes. The response contains an id that identifies the stored recording. Copy that id into the lab definition; do not substitute the local file path.

curl --data-binary \
  @automation-demo/data.xml http://127.0.0.1:18080/api/v1/assets

Save automation-demo/lab.json using the returned id in place of RECORDING_ID. Keep agent-0 as the agent ID to reuse the scenario from this chapter.

{"schemaVersion":1, "name":"Release 1 demonstration",
 "agents":[{
   "id":"agent-0", "name":"Router",
   "endpoint":{"address":"127.0.0.1", "port":1161},
   "dataAssetIds":["RECORDING_ID"]
 }]}
curl --header \
  "Content-Type: application/json" --header \
  "Idempotency-Key: create-demo-1" --data-binary \
  @automation-demo/lab.json http://127.0.0.1:18080/api/v1/labs

Lab creation returns HTTP 202 and an operation id, not the completed lab. Poll the operation, replacing OPERATION_ID below. Wait for status SUCCEEDED and obtain result.id as LAB_ID. FAILED and CANCELLED are terminal states; inspect errorCode on failure.

curl \
  http://127.0.0.1:18080/api/v1/operations/OPERATION_ID

Save automation-demo/start.json as {"action":"start","scope":"lab"}. Submit the lifecycle command, then poll its operation before polling the SNMP endpoint.

curl --header \
  "Content-Type: application/json" --data-binary \
  @automation-demo/start.json \
  http://127.0.0.1:18080/api/v1/labs/LAB_ID/actions

Change the file action to pause, resume, stop, or reset for the other lifecycle commands. To run scenario.json, first stop the whole lab and wait for that operation to complete, then submit the scenario.

curl --header \
  "Content-Type: application/json" --data-binary \
  @automation-demo/scenario.json \
  http://127.0.0.1:18080/api/v1/labs/LAB_ID/runs

Poll the returned operation to completion. Its result includes runId; use this as RUN_ID to retrieve the report. An operation can succeed while its scenario report records an assertion failure, so inspect both operation status and report state.

curl --output \
  automation-demo/api-report.json \
  http://127.0.0.1:18080/api/v1/labs/LAB_ID/runs/RUN_ID/report

curl --output \
  automation-demo/api-report.xml \
  "http://127.0.0.1:18080/api/v1/labs/LAB_ID/runs/RUN_ID/report?format=junit"

After exporting reports, DELETE the lab and poll the resulting operation. Stop the server with Ctrl+C when finished.

curl --request DELETE --header \
  @automation-demo/private/auth-header.txt \
  http://127.0.0.1:18080/api/v1/labs/LAB_ID

If you retry a mutation after losing its response, reuse the same Idempotency-Key and the same request body on the same route. A different body with the same key returns a conflict. Do not reuse a key for a new command. To request cancellation, POST an empty JSON object to /api/v1/operations/OPERATION_ID/cancel and poll that cancellation operation. A short command may finish before cancellation takes effect; cancellation does not undo a trap already sent.

Resource under /api/v1	Methods and purpose
/assets	POST: upload a recording or other project resource.
/labs and /labs/{labId}	GET: inspect; POST /labs: create; DELETE a lab: remove it and its reports.
/labs/{labId}/actions	POST: lifecycle action.
/labs/{labId}/agents	GET: list; POST: add to a stopped lab. DELETE /agents/{agentId}: remove from a stopped lab.
/labs/{labId}/agents/{agentId}/overrides	PUT: replace typed values; DELETE: clear the selected context.
/labs/{labId}/agents/{agentId}/faults	PUT: replace the rules array.
/labs/{labId}/agents/{agentId}/traps	POST: send trapName.
/labs/{labId}/runs	POST: start a scenario; GET /runs/{runId}: inspect its report.
/labs/{labId}/events	GET: read events using after and limit query parameters.
/operations/{operationId}	GET: poll completion; POST /cancel: request cancellation.

To import an existing project through REST, upload the project and every referenced file, then POST /labs with projectAssetId and a resources object mapping each exact project reference to its uploaded asset ID. The server does not interpret a project reference as a path on its own filesystem. See the API reference openapi.json, when supplied with your distribution, for the complete interface.