Vela Web API

This page documents our experimental web API for conducting Vela traceroute/ping measurements on the Ark infrastructure. Vela is the on-demand topology measurement service of CAIDA's Archipelago (Ark) infrastructure. Please send feedback regarding desired features, needs and real-life use cases for the Vela web API to ark-info@caida.org.

| Vela Vela Web API Vela MIDAR API Vela aliasq API |

| Download sample Python client code |

Requesting access to the API

We currently limit access to the Vela web interface to academic researchers. We hope to provide access to network operators in the future. Please request a Vela web API key by completing the Vela Account Request form.

Download sample Python client code

Download vela-api, a provided sample Python client code. The sample client code requires the Requests HTTP library ("sudo pip install requests") as well as the docopt package ('sudo pip install docopt').

Supported operations

The Vela web API supports the operations: mons, trace, ping, and get.

mons

Use the 'mons' operation to get a list of the currently usable monitors (the Vela service checks the usability of monitors every minute in the background with active measurement).
trace|ping <monitor_list> <target>

Use 'trace' or 'ping' to request a measurement to run on Ark.
get

Use 'get' to fetch the results of a previously submitted measurement.

Using the sample Python client vela-api

The Vela web API service uses a key to authenticate each user. The following example uses "opensesame". You specify the key with either the "--key" command-line option or by setting the environment variable VELA_API_KEY. For these examples, we leave out the "--key".

The API always responds with a JSON object having one of the following two general structures:

  {"result":"success", ...}

  {"result":"error", "message":"an error message"}

The mandatory "result" field (as well as the HTTP status code) specifies whether a request succeeded or failed. The API returns only one form of "error" response. A "success" response can contain a varying set of additional fields depending on which request was made.

Here are sample outputs for each type of request.

#---------------------------------------------------------------------------
$ ./vela-api mons
URL: https://vela.caida.org/api/monitors?key=opensesame
HTTP response code: 200
HTTP response body:
{
	"result": "success",
	"ipv4": ["san-us", "nrt-jp", ...],
	"ipv6": ["san-us", "hel-fi", ...],
	"by_orgtype": {
		"research": ["san-us", "nrt-jp", ...],
		"educational": ["hel-fi", "hlz-nz", ...],
		...
	},
	"by_country": {
		"USA": ["san-us", "iad-us", ...],
		"Japan": ["nrt-jp"],
		...
	},
	"by_continent": {
		"North America": ["san-us", "yto-ca", ...],
		...
	}
}
#---------------------------------------------------------------------------

The "mons" command returns a JSON object with monitors organized into several categories.

#---------------------------------------------------------------------------
$ ./vela-api trace san-us www.caida.org   # hostname targets resolved by the Vela server
$ ./vela-api ping san-us www.caida.org
$ ./vela-api ping san-us 2001:1900:2254:206a::50:0
$ ./vela-api ping san-us,ams-nl,kgl-rw www.caida.org
$ ./vela-api ping @ipv4 www.caida.org   # from all IPv4-capable monitors

URL: https://vela.caida.org/api/create?vp=san-us%2Cams-nl&destination=www.caida.org&method=ping&key=opensesame
HTTP response code: 200
HTTP response body: {"result":"success","result_id":414}
#---------------------------------------------------------------------------

The result ID allows you to fetch the results for all monitors specified by the submitted request.

#---------------------------------------------------------------------------
$ ./vela-api get 414
HTTP response code: 200
HTTP response body:
{
	"result": "success",
	"id": "414",
	"status": "pending",
	"method": "ping",
	"destination": "192.172.226.123",
	"start_timestamp": 1496275480
}
#---------------------------------------------------------------------------

If a measurement is still in progress, then you'll get a "success" result with status "pending".

#---------------------------------------------------------------------------
$ ./vela-api get 414
HTTP response code: 200
HTTP response body: 
{
	"result": "success",
	"id": "414",
	"status": "completed",
	"method": "ping",
	"destination": "192.172.226.123",
	"start_timestamp": 1496275480,
	"values": {
		"san-us": "P\t192.172.226.247\t192.172.226.123....",
		"ams-nl": "P\t192.42.115.98\t192.172.226.123...."
	},
	"errors": {}
}
#---------------------------------------------------------------------------

For the moment, ping results are in a pseudo-sk_analysis_dump format (tab-separated fields).

#---------------------------------------------------------------------------
$ ./vela-api trace san-us,ams-nl www.freebsd.org
$ ./vela-api get 415
HTTP response code: 200
HTTP response body: 
{
	"result": "success",
	"id": "415",
	"status": "completed",
	"method": "traceroute",
	"destination": "8.8.178.110",
	"start_timestamp": 1496280914,
	"values": {
		"san-us": "{\"version\":\"0.1\",\"type\":\"trace\",\"method\":...",
		"ams-nl": "{\"version\":\"0.1\",\"type\":\"trace\",\"method\":..."
	},
	"errors": {}
}
#---------------------------------------------------------------------------

The API returns traceroute results as a JSON string in the format of sc_warts2json. This allows a user to either deserialize the JSON string into an in-memory structure, or write out the JSON string to a file and run any existing analysis scripts that process sc_warts2json output. In the future, this design could allow for the result format to change at the user's request (e.g., to get sk_analysis_dump-style result).

Due to technical challenges, the topo-on-demand server does not return the full data obtained from scamper for a traceroute/ping. The JSON result returned from the web API only provides a subset of the fields. Below we show a sample of the JSON result for a traceroute:

#---------------------------------------------------------------------------
{
	"version": "0.1",
	"type": "trace",
	"method": "icmp-echo-paris",
	"start": {
		"sec": 1496280914,
		"usec": 0
	},
	"src": "192.42.115.98",
	"dst": "8.8.178.110",
	"hops": [{
		"probe_ttl": 1,
		"probe_id": 1,
		"addr": "192.42.115.1",
		"rtt": 0.259
	}, {
		"probe_ttl": 2,
		"probe_id": 1,
		"addr": "145.145.17.88",
		"rtt": 1.045
	}, {
...
	}, {
		"probe_ttl": 13,
		"probe_id": 1,
		"addr": "8.8.178.93",
		"rtt": 152.297
	}, {
		"probe_ttl": 14,
		"probe_id": 1,
		"addr": "8.8.178.110",
		"rtt": 152.334,
		"dest_resp": true
	}],
	"stop_data": 0,
	"stop_reason": "COMPLETED"
}
#---------------------------------------------------------------------------

The Vela API returns the same amount of detail as the equivalent sk_analysis_dump output. Note: There is one slight deviation from the sc_warts2json format: the hop for the ECHO_REPLY response from the destination is indicated with an extra field, "dest_resp", that does not exist in sc_warts2json.

The HTTP status code for requests will be 200 for success, 404 when you do a "get" on an unused result_id, 400 for a malformed/incomplete request URI, and 500 for an assertion failure, etc.

Future work

return a JSON ping object,
support other ways of submitting a batch of measurements at once (allowing different targets per monitor),
support fetching multiple results with a single network request,
support fetching new results since last attempt (by something like last timestamp or result_id), and
change the topo-on-demand server to return all available warts data.

Please send feedback regarding the vela web API to ark-info@caida.org.