OpenTox REST API [A brief overview]

P. Sopasakis 1 National Technical University of Athens, Greece, 2 IMT Institute for Advanced Studies Lucca, Italy.

Part I The OpenTox framework [design principles] [components] [access control]

Design principles ¡  REST architecture

Design principles ¡  REST architecture – methods

•  GET: read •  POST: create •  PUT: update •  DELETE: delete

Design principles ¡  Linked data (RDF framework & Web ontologies)

Main components

Compound/Conformer Dataset

Algorithm

Validation report

Feature

Model

Model validation

Asynchronous task

Error report

Access control

Access policies

Part II The OpenTox API [with cURL examples]

Features

Features

Features

Request:!curl -X POST --data-binary @myfeature.rdf!http://apps.ideaconsult.net:8080/ambit2/feature!-H Content-type:application/rdf+xml!

Features

Request:!curl -X POST --data-binary @myfeature.rdf!http://apps.ideaconsult.net:8080/ambit2/feature!-H Content-type:application/rdf+xml!

Response:!http://apps.ideaconsult.net:8080/ambit2/feature/10242786!

Compounds/conformers

Compounds/conformers

Request:!curl -H Accept:chemical/x-daylight-smiles !http://apps.ideaconsult.net:8080/ambit2/compound/101 -v!

Request according to the API

Compounds/conformers

Request:!curl -H Accept:chemical/x-daylight-smiles !http://apps.ideaconsult.net:8080/ambit2/compound/101 -v!

Response:!< HTTP/1.1 200 OK!< Date: Mon, 15 Sep 2014 17:34:48 GMT!...!< Server: Restlet-Framework/2.0m6!< Content-Type: chemical/x-daylight-smiles;charset=UTF-8!< Transfer-Encoding: chunked!< !NC(C)Cc1ccccc1.NC(C)Cc1ccccc1.O=S(=O)(O)O!

Response according to the API

Compounds/conformers Loop up for furosemide:

Request:!curl -H Accept:text/uri-list /ambit/compound?search=furosemide&pagesize=1!

Response:!/ambit/compound/148/conformer/143983!

Compounds/conformers Now ask for the value of logD for this compound:

Request:!curl -H Accept:application/json "http://apps.ideaconsult.net:8080/ambit2/compound/184?feature_uris%5B%5D=http%3A%2F%2Fapps.ideaconsult.net%3A8080%2Fambit2%2Ffeature%2F22204"!

Request:!curl -H Accept:text/uri-list /ambit/compound?search=furosemide&pagesize=1!

Response:!/ambit/compound/148/conformer/143983!

Compounds/conformers Now ask for the value of logD for this compound:

Request:!curl -H Accept:application/json "http://apps.ideaconsult.net:8080/ambit2/compound/184?feature_uris%5B%5D=http%3A%2F%2Fapps.ideaconsult.net%3A8080%2Fambit2%2Ffeature%2F22204"! Response:

"dataEntry":[ { "compound":{ "URI":"/ambit2/compound/184", }, "values":{ "/ambit2/feature/22204":-1.210 }!

which returns the requested value:

Request:!curl -H Accept:text/uri-list /ambit/compound?search=furosemide&pagesize=1!

Response:!/ambit/compound/148/conformer/143983!

Datasets [API specs]

¡  GET: ¡  Download in RDF, JSON, CSV, ARFF or other formats, or get a

single feature-value pair for a compound, ¡  Query a dataset, select compounds or features ¡  Get metadata of the dataset

¡  POST: ¡  Create a new dataset on the server,

¡  PUT: ¡  Update the dataset

¡  DELETE: ¡  Delete a dataset, ¡  Delete part of a dataset (some compounds and/or features)

Datasets [RDF representation]

* this structure is determined and understood by the OpenTox ontology.

Algorithms

Algorithms

username=guest!password=guest!

Algorithms

token=`curl -X POST -k 'https://opensso.in-silico.ch:443/auth/authenticate?uri=service=openldap' -d username=$username -d password=$password 2> /dev/null`!token=`echo $token | cut -c10-80`;!

username=guest!password=guest!

Algorithms

token=`curl -X POST -k 'https://opensso.in-silico.ch:443/auth/authenticate?uri=service=openldap' -d username=$username -d password=$password 2> /dev/null`!token=`echo $token | cut -c10-80`;!

username=guest!password=guest!

Algorithms

token=`curl -X POST -k 'https://opensso.in-silico.ch:443/auth/authenticate?uri=service=openldap' -d username=$username -d password=$password 2> /dev/null`!token=`echo $token | cut -c10-80`;!

username=guest!password=guest!

task_uri=`curl -X POST http://opentox.ntua.gr:8080/algorithm/mlr -H subjectid:$token -H Accept:text/uri-list -d dataset_uri=http://apps.ideaconsult.net:8080/ambit2/dataset/R545 -d prediction_feature=http://apps.ideaconsult.net:8080/ambit2/feature/22200 2> /dev/null`!

Algorithms [Task API]

Algorithms [Task API]

while [ $status -eq 202 ]!do! sleep 2! status=$(curl --write-out %{http_code} \! --silent --output /dev/null $task_uri)!done!

Algorithms [Task API]

while [ $status -eq 202 ]!do! sleep 2! status=$(curl --write-out %{http_code} \! --silent --output /dev/null $task_uri)!done!

model_uri=`curl -H subjectid:$token -H Accept:text/uri-list $task_uri 2> /dev/null`!

Algorithms [PMML Transformations]

Example request:!curl -X POST -v -include \! --form pmml=@mypmml-transformation.xml \! --form epsilon=0.03 \! --form kernel=rbf \! -H Content-Type:multipart/form-data \! http://opentox.ntua.gr:8080/algorithm/svm!

Models [Export]

The PMML format is available for some models (planning to provide full support in the future) for the sake of portability and transparency.

Models [Predict]

Models are used to produce predictions given a dataset or a compound. A POST is used to perform such predictions.

Validation

Error reports

If anything goes wrong a

detailed error report is

returned to the client.

Take-home messages ¡  The OpenTox REST API dictates (i) how existing

services can be consumed and (ii) how to build OpenTox-compliant predictive toxicology WSs,

¡ We are still around: ToxBank, eNanoMapper, Bioclipse and other projects support (or contribute to) the OpenTox API,

¡ More info: http://opentox.org and http://opentox.ntua.gr

Thank you for your attention.