The document describes the OpenTox REST API, which provides a standardized way to access predictive toxicology web services and share data. It discusses the API's design principles, main components, access control policies, and features for working with data like compounds, conformers, datasets, algorithms, models, and validation reports. Examples using cURL requests are also provided to illustrate how the API can be used to perform tasks like creating a prediction job, monitoring its status, and retrieving results.

1. OpenTox REST API
[A brief overview]
P. Sopasakis
1 National Technical University of Athens, Greece,
2 IMT Institute for Advanced Studies Lucca, Italy.

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

3. Design principles
¡ REST architecture

4. Design principles
¡ REST architecture – methods
• GET: read
• POST: create
• PUT: update
• DELETE: delete

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

6. Main components
Algorithm
Dataset Compound/Conformer
Validation
report
Feature
Model
Model validation
Error report
Asynchronous task

7. Access control

8. Access policies

9. Part II
The OpenTox API
[with cURL examples]

10. Features

11. Features

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

13. 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!

14. Compounds/conformers

15. Compounds/conformers
Request according
to the API
Request:!
curl -H Accept:chemical/x-daylight-smiles !
http://apps.ideaconsult.net:8080/ambit2/compound/101 -v!

16. Compounds/conformers
Request:!
curl -H Accept:chemical/x-daylight-smiles !
http://apps.ideaconsult.net:8080/ambit2/compound/101 -v!
Response according
to the API
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!

17. 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!

18. Compounds/conformers
Now ask for the value of logD for this compound:
Request:!
curl -H Accept:text/uri-list
/ambit/compound?
search=furosemide&pagesize=1!
Response:!
/ambit/compound/148/
conformer/143983!
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"!

19. 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:
which returns the requested value:
"dataEntry":[ {
"compound":{
"URI":"/ambit2/compound/184", },
"values":{
"/ambit2/feature/22204":-1.210
}!
Request:!
curl -H Accept:text/uri-list
/ambit/compound?
search=furosemide&pagesize=1!
Response:!
/ambit/compound/148/
conformer/143983!

20. 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)

21. Datasets
[RDF representation]
* this structure is determined and understood by
the OpenTox ontology.

22. Algorithms

23. Algorithms
username=guest!
password=guest!

24. 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!

25. 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!

26. 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`!

27. Algorithms
[Task API]

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

29. 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`!

30. 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!

31. 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.

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

33. Validation

34. Error reports
If anything goes wrong a
detaile d er ror report is
ret u r ne d to the client.

35. 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

36. Thank you for your attention.