Dear Christoph,


On 1 November 2010 19:22, Christoph Helma <helma at in-silico.ch> wrote:

> Dear Nina, All,
>
> Excerpts from Nina Jeliazkova's message of Sat Oct 30 09:53:02 +0200 2010:
> > Hello All,
> >
> > We have found somewhat inconsistent documentation, regarding the usage of
> > tasks.  The API wiki says it is either the URL of the result returned, or
> > the task URL.
> >
> > In practice, if the (default) "Accept:application/rdf+xml" header is
> > requested, a task URL is always returned and the task contains
> information
> > if it is completed or not, and if it is completed, then the RDF
> > representation of the task contains the URI of result.
>
> I always had the impression that
>  - POST operations should return the URI of the created object _or_ a task
> URI (i.e. Accept:text/uri-list)
>        - GET operations should return the object representation in OWL-DL
> (by default in RDF/XML format) (i.e. Accept/application/rdf+xml)
>
> I would expect the following workflow for services that require tasks
> (thats how it was implemented in ALU/IST services):
>
> POST to the service - returns task URI
> GET the task URI - returns task rdfxml with status (and URI of the created
> object if status is Completed)
> If status is Completed: GET URI of result object - returns object
> representation (rdfxml by default)
>
> What would be the advantage of getting RDF/XML for a newly created task
> (status would be Created by definition)?
>

Not necessarily, for a quick operation the task might already be completed
and the result returned.  What we could gain is  one HTTP call less.

The confusing point is actually "_or_" in the API - "URI of the created
object _or_ a task URI (i.e. Accept:text/uri-list) "  - it implies one could
receive URI of the result , not the task.  I would suggest to specify that
POST to a service always return a task (URI or representation) , not the URI
of the object.

IDEA implementation is as follows:
- POST to the service - return task URI (if text/uri-list) or RDF/XML of a
task  (if Accept:application/rdf+xml is requested).

- GET the task URI - returns task content in the requested representation
always (e.t. RDF/XML is requested, text-uri-list if requested).
In case of text/uri-list it returns task URI, but if the task is completed,
returns the object URI (with uri-list there is no really other options how
to return the result)

- GET task URI never returns object representation, the result URI  is
available in the task representation.  The reason is the object might be a
huge, and the client application might not necessarily want to receive
entirely at this moment (e.g. might prefer to show it  page by page ).

Best regards,
Nina


>
> Best regards,
> Christoph
>
> >
> > However, if the "Accept:text/uri-list" is requested instead of the
> default
> > RDF, the URL returned by completion will be the one of the result itself
> > (e.g. URL of a dataset with predicted results).
> >
> > Should we change anything, or just try to make the documentation clear?
> > Perhaps make explicit what is being returned if different "Accept:"
> headers
> > are used?
> > Are there implementations that handles these cases differently?
> >
> > 1)Algorithm  http://opentox.org/dev/apis/api-1.1/Algorithm
> > Result: *model URI ,dataset URI,featureURI* , Redirect to task URI for
> time
> > consuming computations
> >
> > Note: Redirect was removed from the API but apparently this page was not
> > updated, there is still reference to 303 status codes.
> >
> > 2)Model  http://opentox.org/dev/apis/api-1.1/Model
> > Result: URI of created prediction dataset (predictions are features),
> task
> > URI for time consuming computations
> >
> > Best regards,
> > Nina
> _______________________________________________
> Development mailing list
> Development at opentox.org
> http://www.opentox.org/mailman/listinfo/development
>