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

>
>
>>
>> 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?

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