On Mon, Nov 8, 2010 at 10:43 AM, Nina Jeliazkova
<jeliazkova.nina at gmail.com> wrote:
> On 8 November 2010 11:40, Martin Guetlein <martin.guetlein at googlemail.com>wrote:
>
>> On Mon, Nov 8, 2010 at 10:09 AM, Nina Jeliazkova
>> <jeliazkova.nina at gmail.com> wrote:
>> > 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).
>>
>> On Mon, Nov 8, 2010 at 10:00 AM, Tobias Girschick
>> <tobias.girschick at in.tum.de> wrote:
>> > I would say yes, as this is what the client requests and expects. Are
>> > there cases that could be problematic?
>>
>> I share Nina's opinion that we should not return the whole data due to
>> performance issues.
>> The question is, what to return if RDF/XML is requested by the client?
>> IMHO, we have the following options:
>>
>> * Always return the task object (as Nina proposed). Drawback:
>> inappropriate for services that are very fast, and do not need a task.
>>
>> * Return value for RDF/XML is undefined. Drawback: we should always
>> support RDF/XML as this is the default format for OT web services.
>>
>> * Return the URI, wrapped in RDF/XML
>>
>> I would go for the last option.
>>
>
> Does it mean introducing another RDF representation just for this case?
>
> How the last option differs from returning Task Object (with completed
> status), which essentially wraps result URI in Task RDF representation?

Hmm, let me think about it one more time. I see your point...
I guess we just have to define something for RDF/XML (whereas as a
developer I would go for text/uri-list in that case). I concur.

Still, I would stick to return the result URI directly for
text/uri-list (if available, task URI otherwise).

What about the others?

Best regards,
Martin


>
> Best regards,
> Nina
>
>
>>
>> Best regards,
>> Martin
>>
>>
>>
>>
>> >
>> >
>> > 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
>> >>
>> > _______________________________________________
>> > 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