aspose file tools*
The moose likes Web Services and the fly likes Does Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login
JavaRanch » Java Forums » Java » Web Services
Bookmark "Does "REST API Design Rulebook" address proper design for idempotency?" Watch "Does "REST API Design Rulebook" address proper design for idempotency?" New topic
Author

Does "REST API Design Rulebook" address proper design for idempotency?

Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4659
    
    5

I find that far too many applications have no support for idempotency. Often it appears that the API designers never considered the topic.

Does the book address this?
Mark Masse
author and iconoclast
Greenhorn

Joined: Nov 08, 2011
Posts: 20
Pat Farrell wrote:I find that far too many applications have no support for idempotency. Often it appears that the API designers never considered the topic.

Does the book address this?


Hi Pat,

Sorry for the delayed response - I somehow missed your post. Can you clarify what you mean by "support" for idempotency? Are you encountering many APIs that seem to "violate the contract" specified by HTTP's methods?

Here's a link for folks that aren't as familiar with the idempotent property of some of HTTP's methods: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.2


WRML and the REST API Design Rulebook
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4659
    
    5

Mark Masse wrote: Can you clarify what you mean by "support" for idempotency? Are you encountering many APIs that seem to "violate the contract" specified by HTTP's methods?


Yes, exactly. The classic example is a duplicate send of a "buy items in shopping cart" command, triggered by a POST. You only want the items once, not two or three times.
Mark Masse
author and iconoclast
Greenhorn

Joined: Nov 08, 2011
Posts: 20
Pat Farrell wrote:
Mark Masse wrote: Can you clarify what you mean by "support" for idempotency? Are you encountering many APIs that seem to "violate the contract" specified by HTTP's methods?


Yes, exactly. The classic example is a duplicate send of a "buy items in shopping cart" command, triggered by a POST. You only want the items once, not two or three times.


Ah I get your point.

One approach/perspective:
If the REST API designer has chosen to model "buy" using an action/controller resource that "triggered" via POST (a reasonable choice), then it is a client's job to enforce or warn about rePOSTing the "model"? The POST method's idempotency can not be influenced by the client or the server. HTTP allows for the POST method to have side effects, so repeat calls to the method will do whatever they do (possibly double billing a credit card). This is why the browser traps the POST form button's clicks and prompts users with "Are you sure that you want to rePOST the form data?"

Clients need to understand (and account for) the nature of any HTTP methods that they use to communicate. Page 27 of my book talks a little bit more about this design concern.

An alternative approach:
A more sophisticated REST API could choose to assign a cart ID or some other piece of state to the model that the server can check against some transaction log (in the back-end) to determine that the transaction/order has already been submitted so there is nothing to do. The API might respond with a 409 "conflict" to indicate to the client that the exact same cart cannot be repurchased.

Another approach:
The interaction could use a conditional POST, with the client adding a precondition that allows the server to verify that they are in sync (state-wise) before proceeding with the action. Page 36 of my book discusses this approach.

I am curious to hear which approach that folks like the best or if anyone has an alternative design approach that they prefer?
Pat Farrell
Rancher

Joined: Aug 11, 2007
Posts: 4659
    
    5

Mark Masse wrote:If the REST API designer has chosen to model "buy" using an action/controller resource that "triggered" via POST (a reasonable choice), then it is a client's job to enforce or warn about rePOSTing the "model"? ....
Clients need to understand (and account for) the nature of any HTTP methods that they use to communicate. Page 27 of my book talks a little bit more about this design concern.


I can't comment on the relative values of your approaches, but I have found that:

1) you can not trust the client software to do reasonable things. Browsers are weird, and you may not be talking to a browser.
2) If you assume that the human client has an IQ higher than a turnip, you are making a huge mistake.
Mark Masse
author and iconoclast
Greenhorn

Joined: Nov 08, 2011
Posts: 20
Pat Farrell wrote:
Mark Masse wrote:If the REST API designer has chosen to model "buy" using an action/controller resource that "triggered" via POST (a reasonable choice), then it is a client's job to enforce or warn about rePOSTing the "model"? ....
Clients need to understand (and account for) the nature of any HTTP methods that they use to communicate. Page 27 of my book talks a little bit more about this design concern.


I can't comment on the relative values of your approaches, but I have found that:

1) you can not trust the client software to do reasonable things. Browsers are weird, and you may not be talking to a browser.
2) If you assume that the human client has an IQ higher than a turnip, you are making a huge mistake.


I don't disagree.

Well, speaking for myself, when I write my own client apps, I know that I will at least use the HTTP methods correctly. I recommend that you all do so as well.
 
 
subject: Does "REST API Design Rulebook" address proper design for idempotency?