Previous posts in this series:
- Ion Torrent Server API, I’d like to introduce you to the MiniLIMS API
- The MiniLIMS 4 column table and it’s PHP manifestation, the TypeInstance
I’d like to suggest a quick round of applause for the RESTful Ion Torrent Server API. I feel funny doing so; it’s like applauding a common sense activity like using a cross walk and not running across the street. API calls via URLs that return JSON text objects really should be the default these days. Sure, maybe you’re in some glacially-paced industry that just made the move from CORBA to SOAP and are thrilled with the readability of bloated XML documents. But for everyone else, GET/POST operations that communicate via lightweight JSON encoded text is just so sensible. Every modern language, and even command line tools like curl, can use a RESTful API; most can encode/decode JSON in a single line. It’s particularly useful for things like real-time instrument monitoring where an AJAX call can get you the current status without reloading a page.
The icing on this cake is the meta-data. The Torrent Server API delivers an object overview at the root and type details under a “schema” path for each data type in the same RESTful form. It’s not going to be directly useful for the MiniLIMS PGM classes, as I’ll described below, but it’s very handy for those of us that abhor reading documentation.
The URLs of the Torrent Server API reflect the hierarchy you’d expect for accessing data from the instrument. Here’s the URL to access a particular experiment, the Torrent name for an instrument run:
http://<torrent-server>/rundb/api/v1/experiment/3/?format=json
The root of the URL is pretty self explanatory: /rundb/api/v1 is the entry point into the API. Though it is certainly nice of them to include the version, if you’re going to do that, a “latest” URL that redirects to the latest version can also be helpful.
The next part, experiment, is the object type. If you only go this far in the path, you’ll get a full listing of all experiments. If you include the final path component (3 in this example) you’ll be accessing a single object using the internally generated id.
The request parameters come in to play in a number of situations. Though only the one format is supported, and it should be the default regardless, they insist that you include the format=json parameter. Beyond this, request parameters can be used to filter results, find by name, sort the returned documents, and support paging of results. For example, if you don’t know the internally generated id of the experiment, you can ask for it by name:
http://<torrent-server>/rundb/api/v1/experiment/?format=json&expName=R_2011_09_01_15_58_12_user_B15-410-r124922-bst9_lib909_run2-ms
You might have noticed the lack of any login credentials in the URL. Torrent Servers do require logins, but it’s http basic authentication. As a result, most URL-handling code can deal with it, including the curl binary. I’ll show you the PHP code later.
This is the JSON document returned by the above URL (marked up a bit by a Chrome plugin):
Pretty straightforward, eh? Things are well formed and id and ‘resource_uri’ are included. One small annoyance is that most fields are camel case, but there are a few underbar word separators. API should clear that up, though.
As an aside, the data that I’m showing comes from an Amazon EC2 instance setup by Adam Kraut here at The BioTeam. Besides being a guru at all things Cloud, including Master Chef credentials, he’s been spinning up these instances for the Ion Torrent Grand Challenge competitors. They’ve been really handy for development.
The schema urls provide great typing guidance for each of the elements for a particular document. Here’s a partial schema for the experiment type.
A great thing to have available- if you’re in to strongly typed systems. Except for the “nullable” field, most of this is kinda pointless in our situation. PHP isn’t strongly typed and, even if it were, MiniLIMS itself treats everything as name-value pairs. Any value checking has to be done in decoupled validation code. The schema also provides a list of filtering and ordering fields (not shown in the screenshot above). This also is unlikely to help us much because we’re going to slurp the data wholesale into MiniLIMS and will take care of searching and sorting with our own mechanisms.
Among the request parameters that can be used are limit and offset. The combination of these two can support a “paging” functionality. If, for example, we weren’t storing the experiment records in MiniLIMS itself, we might want a paged display of, say 20 at a time. For page 1, we’d use limit=20&offset=0; for page 2, we’d use limit=20&offset=20. Again, we’re going to be pulling the data into MiniLIMS to get tighter integration for our end users, so we’ll be able to pass on this as well.
The results: field in the experiment shown above is a URI, clearly pointing to a document of another type. This foreign-key-like pointer is important for tying the data together, but is going to add a minor wrinkle to the API development.
I swear, code is coming soon. Now that we have some of the background, in the next post, I’ll walk through the design of data objects in our API.
Next post in this series:
