Metamolecular Products Blog

Update August 12, 2009: The REST-RPC hybrid API described in this article has been replaced by a fully-RESTful API.

Chemcaster is a tool for building chemically-enabled Web sites. Although it offers a browser-based interface, Chemcaster was also designed to expose its functionality through a Web API. The Chemcaster API makes it possible to programmatically create, read, edit, delete, and process process chemical structures without the need for locally-installed cheminformatics software. In the next few weeks, we'll see some of the ways this API can be used to quickly build Websites with chemical structure content.

About the API

The Chemcaster API is accessed using standard HTTP through a RESTful interface. Content payloads are encoded with XML and delivered using the HTTP verbs GET, PUT, POST, and DELETE. A Chemcaster account automatically grants access to the API. To receive an invitation to create your account, visit our online invitation request page.

Structure is the most fundamental Chemcaster resource, and the only one implemented to date. As testing of Chemcaster continues, expect to see additional resource exposed through the Web API.

Using ActiveResource

Although many HTTP clients can be used to explore the Chemcaster API, including a standard Web browser, one of the most powerful is the ActiveResource framework.

With a Ruby 1.8 installation and RubyGems, ActiveResource can be installed on Unix-based systems by issuing the command:

$ sudo gem install activeresource --no-ri --no-rdoc

Create a Project

Using the Chemcaster browser interface, create a new Registry. Your Registry can be referenced by its unique id, which appears at the end of the URL for the Registry home. The remainder of this tutorial will assume a unique Registry id of "1".

A Short Ruby Chemcaster Client

ActiveResource makes it possible to create extremely concise REST clients, an example of which appears below:

require 'rubygems'
require 'activeresource'

class Structure < ActiveResource::Base
  self.site = 'https://chemcaster.com/registries/:registry_id'
  self.user = 'you@example.com'
  self.password = 'secret'
end

Update: Web API calls now use SSL, so the self.site url needs to start with "https"

Save this file to your working directory with the name chemcaster.rb.

Creating a Structure

Creating a new Structure requires a structure representation in molfile format and an optional name. The following Ruby code will create a Structure called 'benzene':

require 'chemcaster'

molfile = "[NO NAME]\n  CHEMWRIT          2D\nCreated with ChemWriter - http://metamolecular.com/chemwriter\n  6  6  0  0  0  0  0  0  0  0  0 V2000\n    5.0800   -5.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    5.9460   -5.5400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    6.8121   -5.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    6.8121   -4.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    5.9460   -3.5400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    5.0800   -4.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  1  2  2  0  0  0  0\n  2  3  1  0  0  0  0\n  3  4  2  0  0  0  0\n  4  5  1  0  0  0  0\n  5  6  2  0  0  0  0\n  6  1  1  0  0  0  0\nM  END"
benzene = Structure.new :name => "benzene", :molfile => molfile, :registry_id => 1

benzene.save

The above code can be executed by saving it to a file called create.rb and executing it:

$ ruby create.rb

A new structure should have been added to your Registry.

Reading a Structure

We can read back a structure as well. This time using the Interactive Ruby Shell, we could execute the following commands:

$ irb
irb(main):001:0> require 'chemcaster'
=> true
irb(main):002:0> s=Structure.find('benzene', :params => {:registry_id => 1})
=> #<Structure:0xb750ab74 @attributes={"name"=>"benzene", "id"=>"benzene", "molfile"=>"[NO NAME]\n  CHEMWRIT          2D\nCreated with ChemWriter - http://metamolecular.com/chemwriter\n  6  6  0  0  0  0  0  0  0  0  0 V2000\n    5.0800   -5.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    5.9460   -5.5400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    6.8121   -5.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    6.8121   -4.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    5.9460   -3.5400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    5.0800   -4.0400    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n  1  2  2  0  0  0  0\n  2  3  1  0  0  0  0\n  3  4  2  0  0  0  0\n  4  5  1  0  0  0  0\n  5  6  2  0  0  0  0\n  6  1  1  0  0  0  0\nM  END", "inchi"=>"InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H"}, @prefix_options={:registry_id=>1}>

We could also view the raw XML output by pointing a browser to:

http://chemcaster.com/registries/1/structures/benzene.xml.

The other REST operations PUT (update) and DELETE (delete) are also supported with the ActiveResource Chemcaster client.

Conclusions

Chemcaster can be used to quickly build chemistry-focused Web applications though its RESTful API without any locally installed cheminformatics software. As this article shows, writing a client can be quite simple.

Signup for you Chemcaster account today and see for yourself how easy creating rich chemistry Websites can be!