On 24 November 2011 15:13, Reto Bachmann-Gmür <[email protected]> wrote: > On Thu, Nov 24, 2011 at 12:23 PM, Enrico Daga <[email protected]> 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 > > >> 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. cheers, Enrico > > Cheers, > Reto -- Enrico Daga -- http://www.enridaga.net skype: enri-pan
