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 12:59:54 pm | |
| List: | org.apache.incubator.stanbol-dev | |
On 24 November 2011 20:56, Reto Bachmann-Gmür <re...@apache.org> wrote:
On Thu, Nov 24, 2011 at 3:28 PM, Enrico Daga <enri...@gmail.com> wrote:
On 24 November 2011 15:13, Reto Bachmann-Gmür <re...@apache.org> wrote:
On Thu, Nov 24, 2011 at 12:23 PM, Enrico Daga <enri...@gmail.com> wrote:
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?
I think /jobs/1234 should not return a link-rel or redirect to /jobs/1234/output till the output is available, so /jobs/1234/output would return a 404 while the job is not finished but nobody should point to this uri as long as the job isn't finished. /jobs/1234 could return a 200 response with a refresh header as long as the job didn't yet complete.
This way would be clearer, and job monitoring would happen only from the /jobs/1234 resource.
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.
Agreed, /jobs/1234 and /jobs/1234/output can do content negotiation and have a content-location header pointing to a uri that doesn't do conneg but just returns the format of the current response.
Well, if the above assumption is that /output should not exists before job completion, we don't need content-negotiation, just 404
Don't understand. While the resource doesn't exist conneg isn't needed, but once the result is computed it might be made available in different formats so that conneg could be useful.
I misunderstood, I thought you was referring to the 404 case, of course conneg is needed when the job is ready.
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)
I don't see the rationale for not having "test/" in the second uri path, the pending and terminated jobs all belong to the same service and I would thus prefer them to share the same service-dependent uri prefix.
The reason is to decouple the job rest service (used for monitoring) from the service which creates the job and can represent the output. This has the benefit to guarantee consistency between services on how this process is managed, but leaving the flexibility on how to create a job and on how to handle output. It also allow us to improve further the api and have all jobs-enabled services to be in, for example progress monitoring, listing of all available jobs, massive deletion, statistics (why not?) and so on are all things that would require a centralized management. IMHO there is no issue on having the /jobs/test (/reasoners/.../job, /anyother/?job=true) service create and handle output, and the /jobs service to manage status, deletion and infos.
Ok, I see. While some features (like listing all pending jobs) are possible with a centralized service having a library to support services following the described pattern without requiring the job-manager service also has advantages (mainly looser coupling, the service can be deployed to an osgi environment without requiring the job-manager service). What about having a library so that all services can independently provide job-management and define a status-service interface so that an optional service can collect information from the individual services managing jobs?
This is a good option, we could provide a jax-rs abstract resource implementing methods for creating and pinging background jobs, including response building. My only concern is that we could not be able to force the defined rest interface to be fully respected (since annotations should not work on an abstract class), or maybe there is a solution I don't see now. I think it is a value to have a commonly shared rest interface for long term operations. Will check better tomorrow ;)
cheers Enrico
Ciao, Reto
-- Enrico Daga
-- http://www.enridaga.net skype: enri-pan