On Mon, 2010-11-08 at 09:55 +0100, Martin Guetlein 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.
> 
> * 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.
> 
> * If a service does not return a task and Accept:application/rdf+xml
> is set, should the complete result object be returned?

I would say yes, as this is what the client requests and expects. Are
there cases that could be problematic?

best regards,
Tobias

> 
> 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.-Bioinf. Tobias Girschick

Technische Universität München
Institut für Informatik
Lehrstuhl I12 - Bioinformatik
Bolzmannstr. 3
85748 Garching b. München, Germany

Room: MI 01.09.042
Phone: +49 (89) 289-18002
Email: tobias.girschick at in.tum.de
Web: http://wwwkramer.in.tum.de/girschick