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.

So from my point of view the API with the __or__ is fine, maybe we
should make the implementation a bit more clear.

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