1

I've been wrestling with the problem of representing a checkout / checkin system via a REST api.

To give you a small example our system handles nodes and we need a way for one user to be able to lock this node and then make changes to it and then commit it.

So I was thinking something like

  • /nodeId (this is the base location for a node and provides an up to date checked in revision read only view of the node)
  • /nodeId/edited (posting to here creates an edited version of the doc this is checkout, gettting gets the edited version, and putting makes a change)

Now I want to represent checkin, im tempted to say that POSTing to /nodeId/edited again will commit the edited document but then we are, giving post two distinct meanings. I could create another checkin endpoint but that seems messy? Another alternative is having a POST to /nodeId which creates the edited version but again this seems confused.

PiersyP
  • 5,003
  • 2
  • 33
  • 35

1 Answers1

2

To lock/checkout a Resource, POST to /nodeId with the partial document {"locked":"true"}. The server must handle Resource state and check if the Resource can be locked etc. The server could answer 204 No Content if the lock suceeded and 409 Conflict if the lock was not possible.

To unlock/checkin the locked Resource, POST to /nodeId with the partial document {"locked":"false", "someKey":"someValue", ...}. The server must handle Resource state, check if the Resource is locked, and update it usinng the POSTed data. Again, the server could answer 204 No Content if the unlock suceeded and 409 Conflict if not.

Edit: added possible HTTP status codes.

Edit 2: There is no "endpoint" in REST like in SOAP. You manipulate Resources, you don't call methods.

  • Hi Tichodroma, thanks for your answer. This is also a method I considered although this approach does not seem to be the restful approach to me. I was under the impression that the verbs POST,PUT,GET and DELETE should map to add, edit, retrieve and delete operations respectively. In your example post is not corresponding to addition of a node, in fact I would say that your example is essentially an RPC, you are sending some data to that identifies a method to invoke and not treating /nodeId as a resource. Please let me know if you think my understanding is incorrect. Thanks Piers – PiersyP Sep 07 '12 at 15:06
  • My idea is not RPC but something called a partial update: using POST against the Resource with only a partial represenation (here: JSON) that includes only those properties of the Resource that should be changed. To add a *new* Resource, you would POST against some collection like `/nodes`. –  Sep 07 '12 at 15:43
  • Thanks for the clarification Tichodroma, its starting to make a bit more sense. One thing though, why are you using POST and not PUT ? My understanding is that POST should be used for creating a resource and PUT for updating? Thanks Piers – PiersyP Sep 07 '12 at 16:40
  • Dude?? What's crackin, ur so close to getting this answer, just need to know about POST and PUT?? Easy – PiersyP Sep 11 '12 at 18:19
  • You are right. PUT would be better: http://stackoverflow.com/questions/630453/put-vs-post-in-rest – scotru Apr 04 '13 at 03:45