11 messages in org.apache.incubator.stanbol-devRe: Reasoners jobs REST interface| From | Sent On | Attachments |
|---|---|---|
| Enrico Daga | Nov 18, 2011 6:45 am | |
| Bertrand Delacretaz | Nov 18, 2011 7:22 am | |
| Enrico Daga | Nov 21, 2011 1:43 am | |
| Bertrand Delacretaz | Nov 24, 2011 2:48 am | |
| Enrico Daga | Nov 24, 2011 3:22 am | |
| Reto Bachmann-Gmür | Nov 24, 2011 6:13 am | |
| Enrico Daga | Nov 24, 2011 6:28 am | |
| Reto Bachmann-Gmür | Nov 24, 2011 11:56 am | |
| Enrico Daga | Nov 24, 2011 12:59 pm | |
| Reto Bachmann-Gmür | Nov 24, 2011 11:27 pm | |
| Reto Bachmann-Gmür | Nov 25, 2011 11:43 am |
| Subject: | Re: Reasoners jobs REST interface | |
|---|---|---|
| From: | Enrico Daga (enri...@gmail.com) | |
| Date: | Nov 24, 2011 3:22:41 am | |
| List: | org.apache.incubator.stanbol-dev | |
Hi Bertrand,
On 24 November 2011 11:48, Bertrand Delacretaz <bdel...@apache.org> wrote:
Hi Enrico,
On Mon, Nov 21, 2011 at 10:43 AM, Enrico Daga <enri...@gmail.com> wrote: ...
2) Watch for job completion
GET /jobs/1234 ... Body contains a link to the job output, for example /jobs/1234/output.txt
...
In the current implementation the Future<?> object used to monitor the status cannot access the Job/Result object before it is complete, so it cannot know the location of the response before. I have thought a solution, anyway, to let the JobManager manage a mapping between ID/Locations delegating to a Job.buildResponseLocation(String jobId) before starting the job...
Ok, at the interface design level I'd say "I don't care" ;-)
As you say, the job manager should keep a mapping that allows for output.txt to point to the right data, and if needed output.txt can also do an http redirect to the right location. Yes
...So, the info should include: - Status (running|finished) - Location - Accept - Delete info...
Ok, for Location and Accept I suggest (example):
link rel=job-output type=text/plain href=/jobs/1234/output.txt link rel=job-output type=application/json href=/jobs/1234/output.json etc..
Actually the Jobs rest service does not support the handling of the output, but just returns infos about the job. I think that the output link should point to the original rest service. We should assume that who starts the job knows the rest interface needed to obtain the result, since different services accepts different content type and support different jersey writers (but maybe you were assuming this already, and write /jobs/1234/output as example...). The Jobs service will represent the job and explain how to obtain the result, in the way you suggested for HTML requests and in a JSON format, if requested.
3) Read job output GET to the path returned in 2), /jobs/1234/output.txt in this example. Might return 404 as long as the job is not finished, with HTML or JSON content that points to the parent job resource, /jobs/1234.
In this we can distinguish non existent resources and non complete jobs only by parsing the content. Could make sense add a Content-Location[1] header pointing to the job, if it is not ready? That should provide information about the job status (in the future progress monitoring, for example) and could help distinguish non ready jobs output and non existent resources...
I'm not a fan of http headers to indicate application-level state...that's not browser-friendly.
How about this:
GET /jobs/1234 returns job info with a link rel=output to /jobs/1234/output.txt GET /jobs/1234/output.txt returns 404 if job not finished GET /jobs/1234/output.txt returns 204 if job finished but produced no output
While I agree on the 204 addition for empty responses, this does not solve the 404 ambiguity (non existant resource / non finished job), am I wrong? And, adding a Content-Location header does not prevent us to also include a body with a JSON or HTML description of the status with a reference to the job. Since this step - IMHO - is demanded to each single service, we must only agree on the requirements they must supply (and maybe prepare a reusable library to easily satisfy it - /jobs/webutils).
For the moment, the /reasoners/jobs/324234 endpoint (for obtaining the output of a reasoners job) returns 404 + content-location header + body with description or 200 on success + result.
In the meantime I have committed a first implementation in commons/jobs/api and commons/jobs/web (I will include README soon). The /jobs endpoint supports a way of creating test jobs, to test the service and provide an exemplary implementation for the endpoints that want to exploit it:
- /jobs/test -> 201 Created, with location /jobs/1234 - /jobs/1234 -> 200 With info and link to output - /jobs/test/1234 handles the output, 404+explanations and link to job or 200 if ready (with result)
cheers
Enrico
This will work both from a browser and from better http clients, WDYT?
Ciao, -Bertrand
-- Enrico Daga
-- http://www.enridaga.net skype: enri-pan