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.
<HTTP method> <repository URL>/<VRI>/<shortcuts>/<method>?<parameters> <request body>
<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¶m2=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
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)
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,
…/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.
The second example above shows how to grab results in json format. That’s very, very useful.
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
POST/GET <repository URL>/login user=<username>&pass=<password>
POST/GET <repository URL>/logout
Searching the repository
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.