Datastream REST API

The following document describes the REST API provided by DSAPI2, as of Feb 22 2011.

The DSAPI2 REST service provides endpoints that allow clients to fetch data and metadata about DSAPI2 streams, as well as token data from the streams. In addition, the REST service can generate simple charts for numeric data, suitable for user-facing display.

Many of the REST calls provide output in more than one format. Supported formats include the following (note that not every endpoint supports every format):

"json": Javascript Object Notation
"xml": XML
"html": HTML
"csv": Comma-Separated Values
"chart": Data chart (as image)
"img": Frame image data
"sos": SOS format
"rdf": RDF/XML
"rss": RSS 2.0
"zip": ZIP archive of requested data

REST endpoints are in the following syntax:

/{request}/{param1}/{value1}/{param2}/{value2}/.../{paramN}/{valueN}

where "request" identifies the type of request being made, and "param" and "value" refer to parameters and their values. For example, the following endpoint is a "list" request, with a "format" parameter whose value is "xml":

/list/format/xml

most endpoints take a "uri" parameter which identifies the stream being queried. Note that any "/" characters in the URI need to be escaped; the exception to this requirement is if "uri" is the final parameter in the request. For example, the following "window" request is targeting the stream with the URI "urn:streams/snorb7/twitter":

/window/start/first/end/last/format/html/uri/urn:streams/snorb7/twitter

Supported endpoints

List

List streams. Returns the URIs of all (or selected) streams. For HTML format, returns a list with human-readable names for each stream, which are hyperlinked to calls against the "window" endpoint.

Parameters:

format - desired result format (supported: html, xml, json)
site (optional) - list only the streams at the given "site" (value should be the URI of a site). A site is any arbitrary grouping of streams. Some fetchers associate multiple streams with a single site.

Example:

/list/format/xml

Frame

Return a single frame of data from a stream. Note that the MIME type of the response is determined by the stream. If each frame is plain text, it will be set to text/plain; if each stream is a TIFF image, it will be set to image/tiff, etc.