Results
List results
Get a list of results.
URL Parameters
Name | Description |
---|---|
page |
integer (optional) See Paging |
limit |
integer (optional) See Paging |
detailed |
boolean (optional) See Summary / Detailed Representations |
filter |
string (optional) See Filtering |
sort |
string (optional) See Sorting |
format |
string (optional) Choices: json , csv Default: json |
Response
200 OK
{
"timestamp": "2016-04-13T15:52:57.723239785-04:00",
"data": [
{
"id": "20160331094706",
"created": "2016-03-31T09:47:06.605983-04:00",
"updated": "2016-03-31T09:47:06.605983-04:00",
"active": false,
"status": "stopped",
"pass": 0,
"fail": 0,
"alerts": 0,
"duration": 32,
"size_on_disk": 84790,
"starred": false,
"archived": false,
"package_name": "one",
"device_name": "Device Foo",
"package_id": "1043",
"device_id": "12",
"config_id": "1011",
"user_id": "1",
"tags": []
},
{
"id": "20160331094643",
"created": "2016-03-31T09:46:43.137471-04:00",
"updated": "2016-03-31T09:46:43.137471-04:00",
"active": false,
"status": "stopped",
"pass": 0,
"fail": 0,
"alerts": 0,
"duration": 12,
"size_on_disk": 78253,
"starred": false,
"archived": false,
"package_name": "one",
"device_name": "Device Bar",
"package_id": "1042",
"device_id": "10",
"config_id": "1010",
"user_id": "1",
"tags": []
}
],
"links": {
"current": 1,
"first": 1,
"last": 6,
"limit": 2,
"next": 2,
"total": 12
}
}
Response
200 OK with ?format=csv
Content-Type: text/csv
Content-Disposition: inline; filename="results.csv"
id,created,updated,result,status,loops,tests,pass,fail,duration,size_on_disk,starred,archived,result_dir,agent_name,package_name,device_name,config_name,package_id,device_id,config_id,user_id,note,pause_message,tags,testcases,options
20160414112200,2016-04-14 11:22:01.012153 -0400 EDT,2016-04-14 11:22:01.012153 -0400 EDT,The package completed successfully,completed,1,3,0,1,37,87283,false,false,/usr/cdrouter-data/results/20160414/20160414112200,localhost,one,Device Foo,default.conf,1048,1016,12,1,,,,"cdrouter_http_270,final,start",
20160414111554,2016-04-14 11:15:56.229233 -0400 EDT,2016-04-14 11:15:56.229233 -0400 EDT,The package completed successfully,completed,1,3,0,1,51,87283,false,false,/usr/cdrouter-data/results/20160414/20160414111554,localhost,one,Device Bar,default.conf,1047,1015,10,1,,,,"cdrouter_http_270,final,start",
Get a result
Get a result.
Response
200 OK
{
"timestamp": "2016-04-14T08:37:47.35607734-04:00",
"data": {
"id": "20160329151057",
"created": "2016-03-29T15:10:57.221857-04:00",
"updated": "2016-03-29T15:10:57.221857-04:00",
"result": "The package completed successfully",
"active": false,
"status": "completed",
"loops": 5,
"tests": 2552,
"pass": 0,
"fail": 1150,
"alerts": 0,
"duration": 13963,
"size_on_disk": 4627674,
"starred": false,
"archived": false,
"result_dir": "/usr/cdrouter-data/results/20160329/20160329151057",
"agent_name": "localhost",
"package_name": "default (5 loops)",
"device_name": "Device Foo",
"config_name": "default.conf",
"package_id": "1040",
"package_id": "12",
"config_id": "1008",
"user_id": "1",
"note": "",
"tags": [
"default"
],
"testcases": [
"cdrouter_app_100",
"cdrouter_app_11",
"cdrouter_app_110",
"final",
"start"
],
"options": {
"tags": [],
"skip_tests": null,
"begin_at": "",
"end_at": "",
"extra_cli_args": ""
},
"features": {
"alerts": {
"enabled": false,
"feature": "alerts",
"reason": "enableSuricata testvar is set to no"
}
},
"interfaces": [
{
"name": "lan",
"value": "eth1",
"is_wireless": false,
"is_ics": false
},
{
"name": "wan",
"value": "eth2",
"is_wireless": false,
"is_ics": false
}
]
}
}
Response
404 Not Found
{
"error": "no such result"
}
Stop a result
Stop a running result.
URL Parameters
Name | Description |
---|---|
when |
string (optional) Choices: end-of-test , end-of-loop |
Examples
Stop a running result immediately.
POST /api/v1/results/20160415113526/stop
Stop a running result at the end of the current test.
POST /api/v1/results/20160415113526/stop?when=end-of-test
Stop a running result at the end of the current loop.
POST /api/v1/results/20160415113526/stop?when=end-of-loop
Response
204 No Content
Pause a result
Pause a running result.
URL Parameters
Name | Description |
---|---|
when |
string (required) Choices: end-of-test , end-of-loop |
Examples
Pause a running result at the end of the current test.
POST /api/v1/results/20160415113526/pause?when=end-of-test
Pause a running result at the end of the current loop.
POST /api/v1/results/20160415113526/pause?when=end-of-loop
Response
204 No Content
Unpause a result
Unpause a paused result.
Response
204 No Content
Edit a result
Edit a result.
Example
PATCH /api/v1/results/20160329151057/
{
"starred": true,
"archived": true,
"tags": [
"one",
"two",
"three"
]
}
Response
200 OK
{
"timestamp": "2016-04-14T08:37:47.35607734-04:00",
"data": {
"id": "20160329151057",
"created": "2016-03-29T15:10:57.221857-04:00",
"updated": "2016-03-29T15:10:57.221857-04:00",
"result": "The package completed successfully",
"active": false,
"status": "completed",
"loops": 5,
"tests": 2552,
"pass": 0,
"fail": 1150,
"alerts": 0,
"duration": 13963,
"size_on_disk": 4627674,
"starred": true,
"archived": true,
"result_dir": "/usr/cdrouter-data/results/20160329/20160329151057",
"agent_name": "localhost",
"package_name": "default (5 loops)",
"device_name": "Device Foo",
"config_name": "default.conf",
"package_id": "1040",
"package_id": "12",
"config_id": "1008",
"user_id": "1",
"note": "",
"tags": [
"one",
"two",
"three"
],
"testcases": [
"cdrouter_app_100",
"cdrouter_app_11",
"cdrouter_app_110",
"final",
"start"
],
"options": {
"tags": [],
"skip_tests": null,
"begin_at": "",
"end_at": "",
"extra_cli_args": ""
},
"features": {
"alerts": {
"enabled": false,
"feature": "alerts",
"reason": "enableSuricata testvar is set to no"
}
},
"interfaces": [
{
"name": "lan",
"value": "eth1",
"is_wireless": false,
"is_ics": false
},
{
"name": "wan",
"value": "eth2",
"is_wireless": false,
"is_ics": false
}
]
}
}
Delete a result
Delete a result.
Response
204 No Content
Subscribe to a result’s updates
Subscribe to a result’s updates via a long polling mechanism.
URL Parameters
Name | Description |
---|---|
updates |
string (required) Must be empty (initial request) or subscription ID |
Example
Subscribe to updates for result 20160329151057
by making an initial
request with an empty ?updates
URL parameter. CDRouter will return
a subscription ID via the id
response field. In the example
response below, the subscription ID is 123
.
GET /api/v1/results/20160329151057/?updates
Response
200 OK
{
"timestamp": "2020-02-12T10:48:31.045109703-05:00",
"data": {
"id": "123",
"timestamp": "2020-02-12T10:48:31.045109073-05:00",
"progress": {
"finished": 0,
"total": 226,
"progress": 0,
"unit": "percentage"
},
"running": {
"id": "20200212104826",
"seq": "1",
"loop": "1",
"result": "running",
"retries": 0,
"started": "2020-02-12T10:48:31.011715-05:00",
"duration": 0,
"flagged": false,
"name": "start",
"description": "CDRouter Startup",
"skip_name": "",
"skip_reason": "",
"log": "start.txt",
"keylog": "",
"note": ""
}
}
}
Subsequent update requests must set the ?updates
URL parameter to
this value. CDRouter will wait up to 10 seconds before sending a
response if there are no pending updates to return. The updates
response field is an array containing a mix of
Result and Test
Result objects,
one for each update that occurred since the last request with the
given subscription ID was received, from oldest to newest.
Note: Subscription ID’s expire 30 seconds after their last use.
In the example response below, the first element in the updates
response field is a Result object and the second is a Test Result
object.
GET /api/v1/results/20160329151057/?updates=123
Response
200 OK
{
"timestamp": "2020-02-12T10:48:31.045109703-05:00",
"data": {
"id": "123",
"timestamp": "2020-02-12T10:48:31.045109073-05:00",
"progress": {
"finished": 0,
"total": 226,
"progress": 0,
"unit": "percentage"
},
"running": {
"id": "20200212104826",
"seq": "1",
"loop": "1",
"result": "running",
"retries": 0,
"started": "2020-02-12T10:48:31.011715-05:00",
"duration": 0,
"flagged": false,
"name": "start",
"description": "CDRouter Startup",
"skip_name": "",
"skip_reason": "",
"log": "start.txt",
"keylog": "",
"note": ""
},
"updates": [
{
"result": "",
"status": "running",
"loops": 1,
"tests": 228,
"pass": 0,
"fail": 0,
"duration": 0
},
{
"id": "20200212104826",
"seq": "2",
"loop": "1",
"result": "pending",
"retries": 0,
"started": "0001-01-01T00:00:00Z",
"duration": 0,
"flagged": false,
"name": "cdrouter_dhcp_server_630",
"description": "Verify DHCP server returns correct DNS server(s)",
"skip_name": "",
"skip_reason": "",
"log": "",
"keylog": "keylog.txt",
"note": ""
}
]
}
}
Get a result’s shares
Get shares for a result.
Response
200 OK
{
"timestamp": "2016-04-15T10:00:22.32676552-04:00",
"data": [
{
"user_id": "307",
"read": true,
"write": false,
"execute": false
},
{
"user_id": "309",
"read": true,
"write": false,
"execute": false
}
]
}
Edit a result’s shares
Edit shares for a result.
Example
PATCH /api/v1/results/123/shares
{
"user_ids": [
309,
307
]
}
Response
200 OK
{
"timestamp": "2016-04-15T10:00:22.32676552-04:00",
"data": [
{
"user_id": "309",
"read": true,
"write": false,
"execute": false
},
{
"user_id": "307",
"read": true,
"write": false,
"execute": false
}
]
}
Export a result
Export a result.
URL Parameters
Name | Description |
---|---|
format |
string (required) Choices: gz |
exclude_captures |
boolean (optional) If true , exclude capture files from export archive |
Response
200 OK
Content-Type: application/x-gzip
Content-Disposition: inline; filename="{id}.gz"
Bulk export results
Bulk export a set of results.
URL Parameters
Name | Description |
---|---|
bulk |
string (required) Must be export |
ids |
string (required) Comma-separated result IDs to export |
exclude_captures |
boolean (optional) If true , exclude capture files from export archive |
Example
GET /api/v1/results/?bulk=export&ids=20160330090544,20160331094643,20160330104643
Response
200 OK
Content-Type: application/x-gzip
Content-Disposition: inline; filename="results-{timestamp}.gz"
Bulk edit results
Bulk edit a set of results.
URL Parameters
Name | Description |
---|---|
bulk |
string (required) Must be edit |
filter |
string (optional) See Filtering |
all |
boolean (optional) If true , apply edits to all results. |
Example
Bulk edit results 20160330090544
and 20160331094643
, setting their
starred
field to true
and tags
field to ["foo", "bar", "baz"]
.
POST /api/v1/results/?bulk=edit
{
"results": [
{"id": "20160330090544"},
{"id": "20160331094643"}
],
"fields": {
"starred": true,
"tags": [
"foo",
"bar",
"baz"
]
}
}
Bulk edit results matching filters user_id=3
and tags@>{working}
,
setting their tags
field to ["not working"]
.
POST /api/v1/results/?bulk=edit&filter=user_id=3&filter=tags@>{working}
{
"fields": {
"tags": [
"not working"
]
}
}
Bulk edit all results, setting their starred
field to false
.
POST /api/v1/results/?bulk=edit&all=true
{
"fields": {
"starred": false
}
}
Response
204 No Content
Bulk delete results
Bulk delete a set of results.
URL Parameters
Name | Description |
---|---|
bulk |
string (required) Must be delete |
filter |
string (optional) See Filtering |
all |
boolean (optional) If true , delete all results. |
Example
Bulk delete results 20160330090544
and 20160331094643
.
POST /api/v1/results/?bulk=delete
{
"results": [
{"id": "20160330090544"},
{"id": "20160331094643"}
]
}
Bulk delete results matching filters user_id=3
and tags@>{not working}
.
POST /api/v1/results/?bulk=delete&filter=user_id=3&filter=tags@>{not working}
Bulk delete all results.
POST /api/v1/results/?bulk=delete&all=true
Response
204 No Content
Get stats for all results
Compute stats for all results.
URL Parameters
Name | Description |
---|---|
stats | string (required) Must be all |
Response
200 OK
{
"timestamp": "2016-04-19T08:20:32.268462627-04:00",
"data": {
"frequent_packages": [
{
"package_name": "default (5 loops)",
"count": "25"
},
{
"package_name": "one",
"count": "16"
},
{
"package_name": "notests",
"count": "12"
},
{
"package_name": "Perf",
"count": "1"
},
{
"package_name": "Example package",
"count": "1"
},
{
"package_name": "Example package 2",
"count": "1"
}
],
"package_names": [
{
"package_name": "Perf"
},
{
"package_name": "default (5 loops)"
},
{
"package_name": "Example package"
},
{
"package_name": "Example package 2"
},
{
"package_name": "notests"
},
{
"package_name": "one"
}
]
"frequent_devices": [
{
"device_name": "Device Foo",
"count": "25"
},
{
"device_name": "Device Bar",
"count": "16"
}
],
"device_names": [
{
"device_name": "Device Foo"
},
{
"device_name": "Device Bar"
}
]
}
}
Get stats for a set of results
Compute stats for a set of results.
URL Parameters
Name | Description |
---|---|
stats | string (required) Must be set |
Example
POST /api/v1/results/?stats=set
[
{
"id": "20160330090544"
},
{
"id": "20160331094643"
}
]
Response
200 OK
{
"timestamp": "2016-04-19T08:23:34.314106113-04:00",
"data": {
"frequent_failures": [
{
"name": "cdrouter_app_100",
"count": "50"
},
{
"name": "cdrouter_app_11",
"count": "50"
},
{
"name": "cdrouter_app_110",
"count": "50"
},
{
"name": "cdrouter_app_12",
"count": "50"
},
{
"name": "cdrouter_app_15",
"count": "50"
},
{
"name": "cdrouter_app_16",
"count": "50"
},
{
"name": "cdrouter_app_17",
"count": "50"
},
{
"name": "cdrouter_app_18",
"count": "50"
},
{
"name": "cdrouter_app_2",
"count": "50"
},
{
"name": "cdrouter_app_21",
"count": "50"
}
],
"longest_tests": [
{
"name": "cdrouter_app_100",
"duration": "60"
},
{
"name": "cdrouter_app_3",
"duration": "22"
},
{
"name": "cdrouter_mptcp_2",
"duration": "20"
},
{
"name": "start",
"duration": "17"
},
{
"name": "cdrouter_mptcp_1",
"duration": "10"
},
{
"name": "cdrouter_app_16",
"duration": "10"
},
{
"name": "cdrouter_app_124",
"duration": "10"
},
{
"name": "cdrouter_app_130",
"duration": "10"
},
{
"name": "cdrouter_app_131",
"duration": "10"
},
{
"name": "cdrouter_app_12",
"duration": "10"
}
],
"result_breakdown": {
"passed": "3",
"failed": "1076",
"skipped": "1400",
"alerted": "0"
},
"time_breakdown": {
"passed": "23",
"failed": "13085"
}
}
}
Diff a set of results
Compute a diff for a set of results.
URL Parameters
Name | Description |
---|---|
stats | string (required) Must be diff |
Example
POST /api/v1/results/?stats=diff
[
{
"id": "20160330090544"
},
{
"id": "20160331094643"
}
]
Response
200 OK
{
"timestamp": "2018-02-06T08:12:40.746902633-05:00",
"data": {
"tests": [
{
"name": "ipv6_basic_1",
"summaries": [
{
"id": "20140410111436",
"seq": "0",
"result": "",
"alerts": 0,
"duration": 0,
"flagged": false,
"name": "",
"description": ""
},
{
"id": "20140905142044",
"seq": "2",
"result": "pass",
"alerts": 0,
"duration": 0,
"flagged": false,
"name": "ipv6_basic_1",
"description": "Verify DUT forwards packets with multiple extension headers"
},
{
"id": "20140905143819",
"seq": "2",
"result": "pass",
"alerts": 0,
"duration": 0,
"flagged": false,
"name": "ipv6_basic_1",
"description": "Verify DUT forwards packets with multiple extension headers"
}
]
},
{
"name": "ipv6_basic_2",
"summaries": [
{
"id": "20140410111436",
"seq": "0",
"result": "",
"alerts": 0,
"duration": 0,
"flagged": false,
"name": "",
"description": ""
},
{
"id": "20140905142044",
"seq": "3",
"result": "pass",
"alerts": 0,
"duration": 0,
"flagged": false,
"name": "ipv6_basic_2",
"description": "Verify DUT responds to packets with multiple extension headers"
},
{
"id": "20140905143819",
"seq": "3",
"alerts": 0,
"result": "pass",
"duration": 0,
"flagged": false,
"name": "ipv6_basic_2",
"description": "Verify DUT responds to packets with multiple extension headers"
}
]
},
{
"name": "ipv6_basic_3",
"summaries": [
{
"id": "20140410111436",
"seq": "0",
"result": "",
"alerts": 0,
"duration": 0,
"flagged": false,
"name": "",
"description": ""
},
{
"id": "20140905142044",
"seq": "4",
"result": "pass",
"alerts": 0,
"duration": 3,
"flagged": false,
"name": "ipv6_basic_3",
"description": "Verify DUT discards packets with unknown extension headers"
},
{
"id": "20140905143819",
"seq": "4",
"result": "pass",
"alerts": 0,
"duration": 3,
"flagged": false,
"name": "ipv6_basic_3",
"description": "Verify DUT discards packets with unknown extension headers"
}
]
}
]
}
}
Get a result’s stats
Compute stats for a result.
URL Parameters
Name | Description |
---|---|
stats | string (required) Choices: all , progress , summary |
Response
200 OK with ?stats=all
{
"timestamp": "2016-04-14T10:14:33.913398648-04:00",
"data": {
"result_breakdown": {
"failed_at_least_once": [
{
"name": "cdrouter_basic_10",
"count": "2"
}
],
"passed_every_time": [
{
"name": "cdrouter_basic_1",
"count": "1"
},
{
"name": "cdrouter_dhcp_server_1",
"count": "1"
},
{
"name": "cdrouter_firewall_1",
"count": "1"
}
]
},
"progress": {
"finished": 15,
"total": 15,
"progress": 100,
"unit": "percentage"
}
}
}
Response
200 OK with ?stats=progress
{
"timestamp": "2016-04-14T10:11:02.970811271-04:00",
"data": {
"finished": 1,
"total": 1,
"progress": 100,
"unit": "percentage"
}
}
Response
200 OK with ?stats=summary
{
"timestamp": "2016-04-14T10:15:37.942225525-04:00",
"data": {
"result_breakdown": {
"passed": "17",
"failed": "0",
"skipped": "14",
"alerted": "0"
},
"test_summaries": [
{
"id": "20150818093716",
"seq": "1",
"result": "pass",
"alerts": 0,
"duration": 86,
"flagged": false,
"name": "start",
"description": "CDRouter Startup"
},
{
"id": "20150818093716",
"seq": "2",
"result": "pass",
"alerts": 0,
"duration": 0,
"flagged": false,
"name": "cdrouter_basic_1",
},
{
"id": "20150818093716",
"seq": "4",
"result": "pass",
"alerts": 0,
"duration": 188,
"flagged": false,
"name": "cdrouter_pppoe_client_1",
}
]
}
}
List logdir files
Get a list of logdir files.
URL Parameters
Name | Description |
---|---|
filter |
string (optional) If given, only return files whose name matches given pattern |
sort |
string (optional) See Sorting |
Example
Return logdir files matching pattern .cap
.
GET /api/v1/results/20160415113526/logdir?filter=.cap
Return logdir files matching pattern cdrouter*_100*.cap
.
GET /api/v1/results/20160415113526/logdir?filter=cdrouter*_100*.cap
Response
200 OK
{
"timestamp": "2016-04-14T09:14:50.870012246-04:00",
"data": [
{
"name": "cdrouter_app_100-lan-m.cap",
"size": 720,
"modified": "2016-03-29T15:32:01.372010169-04:00"
},
{
"name": "cdrouter_app_100-lan.10-m.cap",
"size": 720,
"modified": "2016-03-29T15:41:02.041071458-04:00"
},
{
"name": "cdrouter_app_100-lan.10.cap",
"size": 720,
"modified": "2016-03-29T15:41:02.025071367-04:00"
}
]
}
Response
200 OK with ?format=tgz
Content-Type: application/x-gzip
Response
200 OK with ?format=zip
Content-Type: application/zip
Get a logdir file
Download a logdir file.
Response
200 OK
Content-Type: application/pcap OR text/plain
Content-Disposition: inline; filename="{filename}"
Download logdir archive
Download logdir archive in tgz
or zip
format.
URL Parameters
Name | Description |
---|---|
format |
string (required) Choices: tgz , zip |
exclude_captures |
boolean (optional) If set to true , exclude capture files from archive |
Response
200 OK with ?format=tgz
Content-Type: application/x-gzip
Response
200 OK with ?format=zip
Content-Type: application/zip
Get a test metric
Get a test metric. Available metrics are "bandwidth"
and "latency"
.
Metrics are used by CDRouter’s web GUI to generate performance graphs. See the “Performance Graphs” section of the CDRouter Performance User Guide for a list of tests that provide metrics that can be accessed through this API endpoint.
Example
Get metric bandwidth
for test perf_lan_1
.
GET /api/v1/results/20160219125014/metrics/perf_lan_1/bandwidth
Response
200 OK
{
"timestamp": "2016-04-19T08:32:57.87536398-04:00",
"data": [
{
"log_file": "perf_lan_1.txt",
"timestamp": "2016-02-19T12:50:53.81-05:00",
"metric": "bandwidth",
"value": "939",
"units": "Mbits/sec",
"result": "pass",
"interface_1": "lan",
"interface_2": "lan2"
},
{
"log_file": "perf_lan_1.2.txt",
"timestamp": "2016-02-19T12:52:29.294-05:00",
"metric": "bandwidth",
"value": "941",
"units": "Mbits/sec",
"result": "pass",
"interface_1": "lan2",
"interface_2": "lan"
},
{
"log_file": "perf_lan_1.3.txt",
"timestamp": "2016-02-19T12:53:54.313-05:00",
"metric": "bandwidth",
"value": "938",
"units": "Mbits/sec",
"result": "pass",
"interface_1": "lan",
"interface_2": "lan2"
}
]
}
Get a test metric as CSV
Get a test metric as CSV.
URL Parameters
Name | Description |
---|---|
format |
string (required) Must be csv . |
Example
Get metric bandwidth
for test perf_lan_1
in CSV format.
GET /api/v1/results/20160219125014/metrics/perf_lan_1/bandwidth?format=csv
Response
200 OK
Content-Type: text/csv
Content-Disposition: inline; filename="perf_lan_1_bandwidth_graph.csv"
perf_lan_1.txt,1455904253810,bandwidth,939,Mbits/sec,PASS,lan,lan2
perf_lan_1.2.txt,1455904349294,bandwidth,941,Mbits/sec,PASS,lan2,lan
perf_lan_1.3.txt,1455904434313,bandwidth,938,Mbits/sec,PASS,lan,lan2