Which HTTP Verb should I use to claim and lock an item in a job queue?

Question

I plan on using an HTTP REST interface to connect to a Job Control service.

One key operation is to request a computational Job.

• The caller does not know the ID of the Job; that is what it will be told.
• The job will be marked in the database as locked by the service.
• The data needed for processing of the job will be returned to the caller.

Later on, when the caller is done processing the job, it will send the results back via another REST call.

• Now it knows the ID of the record to be updated.
• The second REST call will update the Job record with the results.
• and change the Job's status and release the lock.
• Only the Success/Fail status needs to be returned.

I am leaning towards using PUT for each operation because no new record is being created; it is being updated in both cases.

Is this proper? Can the first PUT return a large JSON payload with the Job data or does it just return an HTTP status? Should I use a POST instead, even though I am not creating a record, just updating it?

I would have used a GET for the first operation, but a GET is not supposed to change any objects on the service, and I am locking it, which is a change. Is locking a record acceptable in a GET request?

Answer 1

Which HTTP Verb should I use to claim and lock an item in a job queue?

Key idea: a REST API is a facade - your application/service pretends to be an HTTP compliant document store. All of the interesting things that happen are side effects triggered by modifying documents. See Jim Webber, 2011.

With that in mind...

POST is fine. It's okay to use POST.

PUT/PATCH are a good for remote authoring; the client fetches your representation of a resource, makes edits to his local copy, and sends you a copy of the representation (PUT) or a patch document describing the changes (PATCH). The server can then apply those edits to its copy, or not.

So for your specific example, I would expect the client to GET a representation of your resource, change the information in that representation from unlocked to locked, and then to PUT the changed representation back to your server. You server would be expected to update your copy of the representation to match.

It may remind you of a declarative style - the client tells the server what the representation should look like, and it's up to the server to figure out how to do that.

Included for Completeness, NOT Recommened:

The HTTP method registry also includes a method LOCK, with a corresponding UNLOCK. The semantics for these method tokens are defined by the WebDAV specification. If your meaning of LOCK matches that of WebDAV, then using that might be an answer. Note that the specification includes comments like

Any resource that supports the LOCK method MUST, at minimum, support the XML request and response formats defined herein.

Unless you are already in a space where people are expecting to be able to use general-purpose WebDAV clients to interact with your API, that's probably not a good fit.

The HTTP method registry is extendable. So you could define the semantics of your own method token, then push to have it adopted as a standard.