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