Dear OpenTox developers,

As a follow up to our last conference call I am providing an initial
proposal for a REST API as a starting point for discussions: 

REST API proposal:


  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       

General use cases:

  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


    - 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 uses the new resource (e.g. to make predictions)

    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)
      result_uri = POST new_uri parameters # returns URI for result (result_uri)
      GET result_uri until status code is 200 (or 400 for failed requests)
      result = GET result_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)

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 (a few personal opinions):

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:
  
We could start with a 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)

  I am not sure how to indicate resources that have been created, but are not yet available (e.g. during model training)
  
Next steps:

  - discuss and modify proposal
  - define XML for URI collections (should be straightforward)
  - define minimal XML for predictions
  - define http status codes
  - formal documentation (Wiki)
  - extend for more components

Best regards,
Christoph