Sections
You are here: Home » Development » API » API 1.1 - archived version

API 1.1

Interface specifications for OpenTox services (Version 1.1, November 2009).

Common specifications for all APIs

OpenTox components are webservices with a REST (http://en.wikipedia.org/wiki/Representational_State_Transfer) interface.

Parameters

Parameters are posted with a "Content-Type:application/x-www-form-urlencoded" HTTP header. Parameter names are typed in bold letters in the API definitions. Square brackets (e.g. compound_uris[]) indicate that a list of arguments is expected.

Ampersands in URI attribute values (e.g. dataset_uri="/dataset/abc?feature_uri=/feature/x&feature_uri=/feature/z") should be escaped, as explained in http://www.w3.org/TR/html401/appendix/notes.html#ampersands-in-uris

For curl POST requests the -d/--data option should be used to ensure the content type. See http://curl.haxx.se/docs/manpage.html#-d--data for more information on the -d parameter.

Example:

curl -X GET http://{server}/dataset?compound_uris[]={compound_uri1}&compound_uris[]={compound_uri2})

curl -X POST -d 'dataset_uri=http://{server}/dataset/5' http://{server}/algorithm/xxx

Request and submit formats

The default OpenTox format is RDF/XML (with exception of the compound API), but service developers may support additional formats. You can request them, by specifying the MIME type in the "Accept" and "Content-Type" HTTP headers.

If the service cannot serve the requested format, the default format (usually RDF/XML) will be returned.

Examples:

Request a compound in SDF format:

curl -X GET -H "Accept:chemical/x-mdl-sdfile" http://{server}/compound/{id}

Submit a compound in InChI format:

curl -X POST -H "Content-Type:chemical/x-inchi" --data-binary "InChI=1S/C5H10/c1-2-4-5-3-1/h1-5H2" http://{server}/compound

Create a new dataset:

curl -X POST -H "Content-Type:application/rdf+xml" --data-binary@my_data_file.rdf http://{server}/dataset

File uploads

Files can be uploaded by specifying "multipart/form-data" in the Content-Type header.

Bug reports and feature requests

Please use our Issue tracker to report problems with the current API. You can also discuss the APIs on the developers mailing list.

 

Document Actions

Suggestions for the next API

Posted by Jeliazkova Nina at Feb 07, 2010 11:39 AM
1)Avoid using "[]" and non-ascii symbols in parameter names, for example let "feature_uris[]" become "feature_uris". Some framework and tools have problems with "[]"

curl (in smokeping at least)

Restlet:
 Reference ref = new Reference("http://server.org");
 ref.addQueryParameter("feature_uris[]","whatever");

becomes http://server.org?feature_uris%5B%5D=whatever

2)Minimalistic parameter names: "compound_uris" might be just "compound" or even "c". Query length is finite, restrictions depends on browsers and servers

3)Switch the default RDF representation from "application/rdf+xml" to "text/n3". The reason: "text/n3" is less verbose, resulting in less traffic (and perhaps faster processing).

4)Remove dc:identifier from RDF representation of objects, use the object URI as an identifier of the RDF node.

Suggestions for the next API

Posted by Jeliazkova Nina at Mar 05, 2010 08:51 PM

3)Switch the default RDF representation from "application/rdf+xml" to "text/n3". The reason: "text/n3" is less verbose, resulting in less traffic (and perhaps faster processing).

Unfortunately, in Jena implementation, it turns out text/n3 is at least twice slower than rdf/xml generation ...