VCR RESTful API

Just like VRIs provide a standard form to address published computation content, the VCR RESTful API provides a standard form to retrieve this content in structured form.

VCR Repositories provide a REST interface for depositing, retieving and searching computation content. This makes it easy, for example, to write VCR plugins for additional computational platforms and word processors, to develop web applications on top of VCR computation content, and to index computation content on public repositories. It allows to extract knowledge from computation content in new and exciting ways.

The examples below refer to computation content submitted on the Researcher’s tutorial.

Syntax
<HTTP method> <repository URL>/<VRI>/<shortcuts>/<method>?<parameters> <request body>

where -

<HTTP method> is either GET, PUT or POST
<repository URL> is the full address of the repository, e.g. https://vcr-stat.stanford.edu/public. (VCR repositories serve HTTP on port 80 and HTTPS on port 443. The client chooses whether to initiate secure or open communication.)
<VRI> is the Verifiable Result Identifier of a VCR object on the repository
shortcuts are added to indirectly access other objects without using their own VRI explicitly
method is the method to apply to the VCR object
parameters is a string of the form param1=value1&param2=value2&…

Computation content consists of VCR objects. Each VCR object belong to one of five types: Computation, Result, Data, Source and Environment.

Methods available for all objects

…/info?format=<format> : retieve all fields of this object. Default format is JSON.
…/list_fields?format=<format> : retrieve a list of available field names of this object. Default format is JSON.
…/list_method?format=<format> : retrieve a list of available methods for this object. Default format is JSON.
…/qr : retrieve the QR barcode image encoding the object’s VRI

examples

Computation Objects

Computation objects describe a chronicled function invocation, including the VRIs of the input parameters, source code that was executed, and output parameters. Computation objects have no methods, just shortcuts. (Future repository versions will include the re-execute method).

…/creator : shortcut to the computation’s creator (a different Computation object)
…/input/<name> : shortcut to one of the computation’s input parameters (a Result object)
…/output/<name> : shortcut to one of the computation’s output parameters (a Result object)
…/source : shortcut to the computation’s source code (a Source object)

examples

Result Objects

Result objects describe a computation result that was generated by a specific computation. It has an underlying data object which holds that actual data of the result. Results objects have no methods, just shortcuts.

…/creator : shortcut to the results’s creator (a Computation object)
…/data : shortcut to data object underlying the result
…/grab?format=<format> : grab the underlying data object as an environment variable. Default format is Matlab MAT file.

examples

The second example above shows how to grab results in json format. That’s very, very useful.

Data Objects

Data objects store the actual data used or produced by the computation and are by far the most important elements of any computation content. A data object does not hold meta-data about the way it was created (by what process, for instance). It is always paired with a Result object that “tells its creation story”. The methods of data objects allows to retrieve the data they store, whole or parts, in various formats. There are four sub-types: struct_data, graphics_data, numeric_data, and just data. The last one is a generic type.

All data types expose the following two methods

…/summary?format=<format> : a textual summary of the data. Default format is JSON.
…/grab?format=<format> : grab the data object as an environment variable. Default format is Matlab MAT file.

numeric_data objects expose the formatting method
…/numeric?format=<format>&rows=(<r1>..<r2>)&col=(<c1>..<c2>) : get a submatrix indexed by rows and columns. Default format is JSON.

graphics_data objects expose the formatting method
…/graphics?format=<format>&width=<w>&height=<h> : render the graphics in the specified format, width and height. Default format is JPEG. Other formats available include EPS and Matlab FIG.

struct_data objects expose the formatting method
…/struct?format=<format> : request a formatted version of the struct

examples

System commands

Login
POST/GET <repository URL>/login user=<username>&pass=<password>

Logout
POST/GET <repository URL>/logout

Searching the repository

Search
POST/GET <repository URL>/search?<query_string>

where <query_string> is of the form field1=value1&field2=value2&…. Some public repository might choose to deny this option. This makes computation content submitted to the repository secret until a VRI is revealed in publication, as there is no other way to locate the content.