Metamolecular Products Blog

Chemcaster was created with the belief that building chemically-relevant websites is too hard and too expensive. Web services offer unprecedented flexibility and simplifying power for creating Web applications - we wanted to bring that power to chemistry.

But the power Web services offer can only be fully realized with language-specific clients. Up until now, clients for Chemcaster have been largely missing.

We're now happy to announce that two Chemcaster clients are now ready for download: one written in Ruby and the other written in PHP. Both of these clients make use of the new, lightweight, RESTful Chemcaster API based on JSON.

PHP and Ruby represent two of the most widely-used development languages on the Web today. If you're building a site that needs to store, image, or search chemical structures, Chemcaster and its client libraries were designed to make the process faster and cheaper.

Request an invitation today and see for yourself how easy building rich chemistry websites can be with Chemcaster!

We'll soon be unveiling big changes to the Chemcaster Web API aimed at promoting long-term stability while at the same time offering flexibility with future improvements.

The most obvious change will be the use of JavaScript Object Notation (JSON) as the encoding system. This simple, lightweight, and readable notation is an increasingly popular alternative to XML, and is supported by nearly every modern programming language.

Another important change will be full implementation of a RESTful, hypertext-driven API, which will replace the existing REST-RPC hybrid. One practical consequence is that the URL templates documented in the existing API will no longer be used. Instead, the information needed to access additional resources from any point in the system will be encoded by the server itself using hypertext. Rather than working as a map, the new API will work more like a GPS.

Finally, to improve Chemcaster's ease-of-use, we'll be introducing a set of open source language-specific APIs. The first, written in Ruby, is available through its public GitHub repository. This is an early version and subject to change; but it accurately reflects the direction the new API will be taking.

Balancing the opposing needs of flexibility and stability is never easy, and this makes developing APIs particularly difficult. With these changes to the Chemcaster API, we hope to offer a system that can be useful both for today and tomorrow.

Chemcaster is the cheminformatics Web services platform optimized for rapid creation of chemistry-focussed websites. It supports compound registration, exact- and substructure search, and dynamic 2D structure image creation, both through a browser-based administrative interface and a Web API.

We're looking for developers interested in testing Chemcaster with their next project. If the idea of streamlining the creation of your chemistry-focused website sounds interesting, please consider requesting an invitation to create an account.

The Chemcaster Web API documentation is now online.

Chemcaster is the cheminformatics Web services platform optimized for rapid creation of chemistry-focussed websites. The Chemcaster API uses a REST web architecture in which actions combine a Resource addressable through a unique path with one or more of the four HTTP verbs GET, PUT, POST, and DELETE.

To find out more, create your free account today.

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

Chemcaster is a new service designed for creating chemistry-focused websites without cheminformatics software.

One of Chemcaster's central services is the Registry. A Registry is a collection of structures with business rules that determine when and how a structure can be added.

After creating a Registry using the browser-based admin tool, Structures can be added via the Chemcaster Web API. The process consists of:

• Creating an XML file containing the elements "<structure>" and "<name>". Fill <structure> with a V2000 molfile and <name> with a valid name for the structure.
• Issuing an HTTP POST request to https:chemcaster.com/registries/{id}/structures, where {id} is your Registry's identifier.

The XML Payload

As a specific example, to add a pyridine structure to a Registry with ID 223, we could first save the following XML file as "pyridine.xml" in our working directory:

<?xml version="1.0" encoding="UTF-8"?>
<structure>
  <molfile>[NO NAME]
  CHEMWRIT          2D
Created with ChemWriter - http://metamolecular.com/chemwriter
  6  6  0  0  0  0  0  0  0  0  0 V2000
   -1.2400    1.0200    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    0.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    2.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -1.2400    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
  1  2  2  0  0  0  0
  2  3  1  0  0  0  0
  3  4  2  0  0  0  0
  4  5  1  0  0  0  0
  5  6  2  0  0  0  0
  6  1  1  0  0  0  0
M  END</molfile>
  <name>pyridine</name>
</structure>

The POST Request

Next, we could issue a POST request using cURL:

$ curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' -F upload=@pyridine.xml -u you@example.com:password https://chemcaster.com/registries/223/structures

The Response

If successful, the POST request will return a response, the body of which will contain another XML document with details of the Structure we just registered:

<?xml version="1.0" encoding="UTF-8"?>
<structure>
  <inchi>InChI=1S/C5H5N/c1-2-4-6-5-3-1/h1-5H</inchi>
  <molfile>[NO NAME]
  CHEMWRIT          2D
Created with ChemWriter - http://metamolecular.com/chemwriter
  6  6  0  0  0  0  0  0  0  0  0 V2000
   -1.2400    1.0200    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    0.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    2.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -1.2400    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
  1  2  2  0  0  0  0
  2  3  1  0  0  0  0
  3  4  2  0  0  0  0
  4  5  1  0  0  0  0
  5  6  2  0  0  0  0
  6  1  1  0  0  0  0
M  END</molfile>
  <name>pyridine</name>
  <registry-id type="integer">1</registry-id>
  <id>pyridine</id>
</structure>

The new structure is now available at https://chemcaster.com/registries/223/pyridine.

Conclusions

Chemcaster's Registry service simplifies the management of collections of chemical structures. Using nothing more than standard RESTful HTTP, it's possible to programmatically manipulate collections of structures for use in your own Web applications.

Chemcaster now supports exact structure queries, both through the graphical administrative interface and through the Web API.

The new capability can be tested using the curl HTTP client. As an example, prepare a file called query.xml in your working directory with this content - representing an exact structure search for benzene:

<?xml version="1.0" encoding="UTF-8"?>
<query>
  <molfile>[NO NAME]
  CHEMWRIT          2D
Created with ChemWriter - http://metamolecular.com/chemwriter
  6  6  0  0  0  0  0  0  0  0  0 V2000
   -1.2400    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    0.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    2.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -1.2400    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
  1  2  2  0  0  0  0
  2  3  1  0  0  0  0
  3  4  2  0  0  0  0
  4  5  1  0  0  0  0
  5  6  2  0  0  0  0
  6  1  1  0  0  0  0
M  END</molfile>
</query>

We can now issue a POST request, assuming a registry id of 1, to create a new query:

$ curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' -F upload=@query.xml -u you@example.com:password https://chemcaster.com/registries/1/queries

This responds with the following xml and a code of 201 (Created):

<?xml version="1.0" encoding="UTF-8"?>
<query>
  <id type="integer">2</id>
  <molfile>[NO NAME]
  CHEMWRIT          2D
Created with ChemWriter - http://metamolecular.com/chemwriter
  6  6  0  0  0  0  0  0  0  0  0 V2000
   -1.2400    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    0.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    2.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -1.2400    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
  1  2  2  0  0  0  0
  2  3  1  0  0  0  0
  3  4  2  0  0  0  0
  4  5  1  0  0  0  0
  5  6  2  0  0  0  0
  6  1  1  0  0  0  0
M  END</molfile>
</query>

We can read the Query ID ('2') and then retrieve our search results with:

$ curl -H 'Accept: application/xml' -u you@example.com:secret https://chemcaster.com/queries/2

The response contains the original query in molfile format as well as the name and id of the matching structure:

<query>
  <id type="integer">2</id>
  <registry-id type="integer">1</registry-id>
  <molfile>[NO NAME]
  CHEMWRIT          2D
Created with ChemWriter - http://metamolecular.com/chemwriter
  6  6  0  0  0  0  0  0  0  0  0 V2000
   -1.2400    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    0.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    1.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
    0.4921    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -0.3740    2.5200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
   -1.2400    2.0200    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0
  1  2  2  0  0  0  0
  2  3  1  0  0  0  0
  3  4  2  0  0  0  0
  4  5  1  0  0  0  0
  5  6  2  0  0  0  0
  6  1  1  0  0  0  0
M  END</molfile>
  <results type="array">
    <structure>
      <id>16</id>
      <name>benzene</name>
    </structure>
  </results>
</query>

Chemcaster is the Web service for sites with rich chemical content. Request your testing invitation today and see how easy it can be to create your next chemistry Web application.