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
