Torrent Suite™ Software API FAQ

General

What is an API and how do I use it?

An Application Programming Interface (API) provides a well-defined interface to a computing system for accessing system resources and functionality. Torrent Suite provides a REST-ful API, which uses the REST communication model to expose system functionality to client applications. Applications use the API by sending create, read, update and delete requests to the server and processing the responses. API request syntax is described in the Torrent Server REST API v1 Resources document and the semantics of the interface are described in the Torrent Suite™ Software API User Guide.

What is REST?

Representation State Transfer (REST) is a client-server communication model for transferring representations of resources, which can be database or functional components. REST uses HTTP as the communication mechanism without assuming that resource state is maintained between request messages. The Torrent Suite API uses REST as the underlying communication model between client application programs and server resources. Using a noun-verb abstraction, the REST create, read, update and delete methods are the verbs that operate on resources as nouns. Resources are addressable using a Universal Resource Identifier (URI), which is formatted like a typical Web address.

Which programming languages are supported?

As a REST specification, the API is programming language independent. Any language or tools that provides facilities for HTTP communication using the GET, PUT, POST and DELETE methods can interact with Torrent Server using the API. However, for any particular language used, standard Web programming constraints and conventions apply for the language

What is the difference between POST and PUT?

A common acronym used to describe the primary data storage functions is CRUD (Create-Read-Update-Delete). POST and PUT are used to describe similar HTTP functions: Generally, POST corresponds to the create function, creating a new data item, and PUT corresponds to the update function, for modifying an existing data item. You can, however, use also PUT to create a data item. The fundamental difference between the two functions is that PUT is idempotent but POST is not.

What is JSON?

JavaScript Object Notation (JSON) is a language independent data interchange format using JavaScript conventions. JSON is currently the only data transport format supported by the Torrent Suite™ Software API.

Tips

I noticed that the API query returns 20 results maximum. How do I access the rest of them?

by default, the maximum number of resource items returned is 20. To get more items with a single request, set the limit parameter to a higher value, such as 100:

http://myhost/rundb/api/v1/results/?format=json&limit=100

To get all items, set limit to zero:

http://myhost/rundb/api/v1/results/?format=json&limit=0

Be careful because some of the resources on your server may have a very large number of items.

How do I sort the returned results in inverse order?

You can change the way the results are ordered using the order_id query string, inserting a minus (-) symbol before filter name:

http://myhost/rundb/api/v1/results/?format=json&limit=0&order_by=-id

Why is a 301 HTTP status code returned when I try to write to the server?

The most common cause of a 301, redirect, error is failing to terminate the URI with a trailing slash character. Another common error when writing or deleting a resource is to include the resource_uri field in the request body.

What are the previous and next fields in the returned meta data?

If available, these are URI links to the previous and next pages of the resource data, when all of the data was not returned with the current page.

What is the resource_uri field?

The resource_uri field is the URI for a detailed view of the data item. The resource_uri field must not be included in your data structure when writing or deleting a resource, including nested resource_uri fields.

How can I retrieve multiple data items with a single request?

The simplest way to retrieve multiple data items with a single request is to specify all of the data items by id, separated by a colon:

http://myhost/rundb/api/v1/results/1;3?format=json

You can also get multiple results using filters and filter qualifiers to get data items matching specific criteria.

Is there a way to query two fields at once? For example, I wanted to find only those experiments that used a particular library and chip type.

Try something like:

http://myhost/rundb/api/v1/experiment?
  format=json&library=e_coli_dh10b&chipType__contains=316

This returns a list of experiments with the e_coli_dh10b reference library whose chip type contains 316. The ampersand (&) notation separates multiple request parameters.

When I PUT or POST to a resource, do I always need to provide all of the fields in the JSON string in the message body?

In general, yes. The only exception is the rig resource, where the following fields can up read and updated individually:

  • state
  • last_init_date
  • last_clean_date
  • last_experiment
  • version
  • alarms