Rest Web Services

Note: This is the initial proposed OpenTox approach to REST web services.  Please feel free to add comments and proposals.

Current Interfaces for OpenTox web services are provided in the Interfaces section.

See also http://github.com/helma/lazar-webservice for an example documentation.

Description                  URI                      Method   Returns                Format    

Retrieve a list of resources  /resources                GET       List with URIs          XML       

Create a new resource         found in Resources list   POST      URI for new resource    XML       

Get resource representation   URI returned by resource  GET       Resource representation variable  

                              creation or from      

                              Resources list

Delete a resource             see above                 DELETE    none                    none      

Update a resource             see above                 PUT       Resource URI            XML       

Create and get the            see above                 GET       variable                variable  

representation of a resource

without saving it on the

server

Query a resource              see above                 GET       List with URIs          XML

Asynchronous processes:

- user submits data and starts a process, that creates a new resource (e.g. prediction, prediction model, features, report)
- user waits until the new resource is available
- user gets a representation of the new resource

would translate into:

new_uri = POST /resources/{resource_id} parameters # returns URI for new resource (new_uri)

GET new_uri until status code is 200 (or 400 for failed requests)

representation = GET new_uri

Synchronous processes:

- user submits data and waits for a representation of the new resource, no permanent resources are created (e.g. depiction of 2D structure, immediate toxicity predictions, report generation)

we have several options (all of them should return a resource representation)

- construct a URI for the query (e.g. /depict/c1ccccc1)
- POST parameters and receive an representation instead of an URI
- make a GET request with parameters

Although I have no strong preference, I would tend towards the last solution:

- GET, because there is no side effect
- GET with parameters (instead of complex URIs with embedded parameters), because
- there is a clear distinction from getting an existing resource (i.e. GET /resource/id request without parameters)
- we cannot provide a lookup service for all possible URIs
- it resembles old cgi style (very easy to use, preferred by many web programmers)

This would translate into

representation = GET /resources/{resource_id} parameters

Initial API Proposals:¶

Example 1: 2D structure depiction

Asynchronous (for illustration purposes, may not be useful)

Description             URI                 Method  Parameters  Returns                                   Format 

Create a new image      /display            POST    smiles      URI for image (e.g. /display/{image_id})  XML (to be defined) 

Get an image            returned by create  GET     -           image                                     png, jpeg, svg, ...

Synchronous:

Description             URI                 Method  Parameters  Returns                                 Format 

Create and get a image  /display             GET     smiles      image                                   png, jpeg, svg, ...

Example 2: Simple prediction

Asynchronous

Description               URI                   Method  Parameters  Returns                                                       Format 

Create a new prediction   /{method}/{endpoint}  POST    smiles      URI for prediction (e.g. /{method}/{endpoint}/{compound_id})  XML (to be defined) 

Get an prediction         returned by create    GET     -           prediction                                                    XML (to be defined)

Synchronous:

Description                  URI                  Method  Parameters  Returns      Format 

Create and get a prediction  /{method}/{endpoint} GET     smiles      prediction   XML (to be defined)

In both cases each prediction representation should contain at least information about

- algorithm 

- endpoint

- structure

- predicted value

- prediction confidence 

- supporting information

Example 3: Model creation

Asynchronous

Description          URI                  Method  Parameters                       Returns                                    Format 

Create a new model   /{method}            POST   training data, model parameters  URI for model (e.g. /{method}/{endpoint})  XML (to be defined) 

Get an model         returned by create   GET     -                               model representation                       e.g. PMML

Use a model         see Example 2

URI construction

We should provide general construction guidelines, but the authorative URI should come from resource collections or resource constructors.
We should avoid overly complex (and unreadable) URIs, e.g. URIs that incorporate a lot of parameters.

HTTP status codes

Starting minimal set:

200 OK

400 Bad request           (Syntax error)

404 Not found             (Resource not available)

500 Internal Server Error (request failed, e.g. prediction error)

503 Service Unavailable   (resource created, but not yet available (e.g. during model training))