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.
Suggestions for the next API
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.