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 21, 2011 1:43:24 am | |
| List: | org.apache.incubator.stanbol-dev | |
Hi Bertrand,
thank you for your feedback. I like your proposal, some comments are inline.
I would do it differently, I think the API below is simpler and I'm intentionally using content to describe the details of the job status instead of "abusing" HTTP status codes:
1) Create a job
POST to /reasoners/owl/classify or any suitable path that can create jobs. With input that describes what to classify
returns 201 created with Location header pointing to the job (say /jobs/1234) and HTML content that contains <a rel="job" href="/jobs/1234"> (or JSON equivalent if that's useful)
Yes, I think we must add at least JSON if we want to move the semantic of the service in the content of the response instead of at HTTP level
2) Watch for job completion
GET /jobs/1234 Returns 200 if the job exists Body describes the job status, in JSON or HTML Body contains a link to the job output, for example /jobs/1234/output.txt Body contains a comment that mentions the DELETE method described in 4)
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. I think we should also inform the client about which are the supported Accept headers. So, the info should include: - Status (running|finished) - Location - Accept - Delete info
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.
4) Cleanup or interrupt jobs
DELETE /jobs/1234 or DELETE /jobs for all jobs
If a job was running, this requests its termination, and the resource disappears once terminated. Ok, I like this.
This should let you create and watch jobs from a browser, while being machine-friendly.
The /jobs path should be handled by a generic component for long-running jobs, decoupled from the reasoners.
WDYT?
I like this simpler solution and I will start implement it immediately.
If everybody agrees I will create this base Job API as /jobs module in /trunk.
Enrico
[1] http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.14
-Bertrand
-- Enrico Daga
-- http://www.enridaga.net skype: enri-pan