Hi Martin, All,

On 8 November 2010 10:55, Martin Guetlein <martin.guetlein at googlemail.com>wrote:

> Hi All,
>
> I adjusted the Task API. The relevant section can be found at
> http://www.opentox.org/dev/apis/api-1.2/AsyncTask#creating-a-task-post
> and below.
>
> These points could be controversial:
>
> * I defined that a GET task/{id} with result header 'text/uri-list'
> returns the resultURI field of the task (That's the way we implemented
> it at ALU-FR and IST ;-)).
> I am well aware that this is a bit un-restfull, but I think it serves
> our purposes.
>

Less consistent, but might be reasonable exception for text/uri-list.


> * A service may return a Task __or__ the result directly. Even the
> same service may do both, depending on the input. This can be
> distinguished via status code.
>

Just to clarify,  it  should be result URI , not the result object
representation.


>
> * If a service does not return a task and Accept:application/rdf+xml
> is set, should the complete result object be returned?
>

No, I strongly vote against returning object content, because it
deteriorates performance and is less consistent.
URI of the result object should be returned in some way, thus my preference
to return Task object always.   text/uri-list might be an exception.
The client should go to the result resource and read the resource in most
appropriate way.  (e.g. not a large dataset entirely,but paginated, as
decided by the client).


Best regards,
Nina


>
> What do you think?
>
>
> Best regards,
> Martin
>
>
> On Tue, Nov 2, 2010 at 10:46 AM, Nina Jeliazkova
> <jeliazkova.nina at gmail.com> wrote:
> > On 2 November 2010 11:40, Martin Guetlein <
> martin.guetlein at googlemail.com>wrote:
> >
> >> On Tue, Nov 2, 2010 at 10:31 AM, Nina Jeliazkova
> >> <jeliazkova.nina at gmail.com> wrote:
> >> > On 2 November 2010 11:21, Martin Guetlein <
> >> martin.guetlein at googlemail.com>wrote:
> >> >
> >> >> On Tue, Nov 2, 2010 at 9:56 AM, Nina Jeliazkova
> >> >> <jeliazkova.nina at gmail.com> wrote:
> >> >> > Martin,
> >> >> >
> >> >> > On 2 November 2010 10:35, Martin Guetlein <
> >> >> martin.guetlein at googlemail.com>wrote:
> >> >> >
> >> >> >> Dear Nina, Christoph,
> >> >> >>
> >> >> >> What I am doing (implementation wise), is using the http code to
> >> >> >> identify whether the result of a POST call is a task (202) or the
> >> >> >> actual object (200). Doing that there is no unneeded additional
> HTTP
> >> >> >> call, and each service can return the task or the object itself,
> >> >> >> according to how long the process takes.
> >> >> >>
> >> >> >
> >> >> > Do you return object content, or object URI?
> >> >> >
> >> >> > Do you handle "Accept" header with different mime types the same
> way?
> >> >>
> >> >> If the result is computed as task, a POST always returns content-type
> >> >> "text/uri-list", content is the TASK uri, http-code is 202 (The task
> >> >> itself is available in different content-types).
> >> >>
> >> >> Returning the task if the POST accept header rdf, is still on todo
> >> >> list (nobody complained so far).
> >> >>
> >> >
> >> > OK.
> >> >
> >> > BTW, the http code could be 201 (as per wiki page)
> >>
> >> I think it was 202. 201 was for linking to another task see
> >> http://opentox.org/dev/apis/api-1.2/AsyncTask
> >>
> >>
> > Exactly, get URI of a task can return 201, if means it "redirects" the
> > processing to another task.   It is a valid code to expect and has been
> > changed from 303.
> >
> >
> >> >
> >> >
> >> >>
> >> >> On Sat, Oct 30, 2010 at 9:53 AM, Nina Jeliazkova
> >> >> <jeliazkova.nina at gmail.com> wrote:
> >> >> > 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).
> >> >>
> >> >> Why don't you return the TASK uri in that case? IMHO the accept
> header
> >> >> should only affect the format of the object, not the returned object
> >> >> itself.
> >> >>
> >> >
> >> > I guess, because it is redundant - GET of an URI to return the same
> URI.
> >> >
> >> > Makes sense for consistency only.
> >> >
> >> >
> >> >>
> >> >> However, IMHO it is no problem that the web services return the
> object
> >> >> result or the task alternately, as long as it can be distinguished
> via
> >> >> http-code.
> >> >>
> >> >>
> >> > Fine as far as it is clearly specified.  Can we document on the API
> page
> >> > what is the expected behaviour in all cases?
> >>
> >> I think the documentation at the Task API is quite substantial.
> >> What we could additionally point out more clearly is the __or__ case,
> >> that the service could return the object uri directly without task
> >> with http-code 200.
> >> We could add an internal link from the other API pages to this
> >> documentation. I could do that.
> >>
> >> Any objections?
> >>
> >
> >
> > No.  In addition, the doc  should also explicitly  list the behaviour on
> > different Accept headers .
> >
> > Best regards,
> > Nina
> >
> >
> >>
> >> Best regards,
> >> Martin
> >>
> >>
> >> >
> >> > Best regards,
> >> > Nina
> >> >
> >> >
> >> >> Best regards,
> >> >> Martin
> >> >>
> >> >> >
> >> >> >
> >> >> >
> >> >> >>
> >> >> >> So from my point of view the API with the __or__ is fine, maybe we
> >> >> >> should make the implementation a bit more clear.
> >> >> >>
> >> >> >>
> >> >> >
> >> >> >
> >> >> > Thanks,
> >> >> > Nina
> >> >> >
> >> >> >
> >> >> >> Regards,
> >> >> >> Martin
> >> >> >>
> >> >> >>
> >> >> >> On Mon, Nov 1, 2010 at 6:47 PM, Nina Jeliazkova
> >> >> >> <jeliazkova.nina at gmail.com> wrote:
> >> >> >> > 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
> >> >> >> >>
> >> >> >> > _______________________________________________
> >> >> >> > Development mailing list
> >> >> >> > Development at opentox.org
> >> >> >> > http://www.opentox.org/mailman/listinfo/development
> >> >> >> >
> >> >> >>
> >> >> >>
> >> >> >>
> >> >> >> --
> >> >> >> Dipl-Inf. Martin Gütlein
> >> >> >> Phone:
> >> >> >> +49 (0)761 203 8442 (office)
> >> >> >> +49 (0)177 623 9499 (mobile)
> >> >> >> Email:
> >> >> >> guetlein at informatik.uni-freiburg.de
> >> >> >> _______________________________________________
> >> >> >> Development mailing list
> >> >> >> Development at opentox.org
> >> >> >> http://www.opentox.org/mailman/listinfo/development
> >> >> >>
> >> >> > _______________________________________________
> >> >> > Development mailing list
> >> >> > Development at opentox.org
> >> >> > http://www.opentox.org/mailman/listinfo/development
> >> >> >
> >> >>
> >> >>
> >> >>
> >> >> --
> >> >> Dipl-Inf. Martin Gütlein
> >> >> Phone:
> >> >> +49 (0)761 203 8442 (office)
> >> >> +49 (0)177 623 9499 (mobile)
> >> >> Email:
> >> >> guetlein at informatik.uni-freiburg.de
> >> >> _______________________________________________
> >> >> Development mailing list
> >> >> Development at opentox.org
> >> >> http://www.opentox.org/mailman/listinfo/development
> >> >>
> >> > _______________________________________________
> >> > Development mailing list
> >> > Development at opentox.org
> >> > http://www.opentox.org/mailman/listinfo/development
> >> >
> >>
> >>
> >>
> >> --
> >> Dipl-Inf. Martin Gütlein
> >> Phone:
> >> +49 (0)761 203 8442 (office)
> >> +49 (0)177 623 9499 (mobile)
> >> Email:
> >> guetlein at informatik.uni-freiburg.de
> >> _______________________________________________
> >> Development mailing list
> >> Development at opentox.org
> >> http://www.opentox.org/mailman/listinfo/development
> >>
> > _______________________________________________
> > Development mailing list
> > Development at opentox.org
> > http://www.opentox.org/mailman/listinfo/development
> >
>
>
>
> --
> Dipl-Inf. Martin Gütlein
> Phone:
> +49 (0)761 203 8442 (office)
> +49 (0)177 623 9499 (mobile)
> Email:
> guetlein at informatik.uni-freiburg.de
> _______________________________________________
> Development mailing list
> Development at opentox.org
> http://www.opentox.org/mailman/listinfo/development
>