Resource to add and subtract quantities

[Jeferson Daniel]

I am planning a resource that can add and remove products from a cart item quantity, example:

POST /cart-items/1/quantity

{

   "add": 6

}

POST /cart-items/1/quantity

{

   "remove": 2

}

GET /cart-items/1/quantity

{

   "value": 4

}

Is that a good aproach? What are the restful alternatives?

Sorry for my english

[Kijana Woodard]

What is the user/client expecting?

---

From: Jeferson Daniel
Sent: ‎12/‎22/‎2015 7:50 PM
To: API Craft
Subject: [api-craft] Resource to add and subtract quantities

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at https://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Jeferson Daniel]

The client is handling quantities of a product. He can increment and decrement the quantity.

You received this message because you are subscribed to a topic in the Google Groups "API Craft" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/api-craft/NvpcqC_WniU/unsubscribe.
To unsubscribe from this group and all its topics, send an email to api-craft+...@googlegroups.com.

[Carl Sutherland]

Do you have an endpoint to GET /cart-items/1 ?  How's that look?

[Carl Zetie]

I would usually avoid "Add" and "Delete" for the simple reason that they are not idempotent, i.e. if you invoke the method more than once (perhaps because you weren't sure it succeeded the first time?), the final state should be the same. Being idempotent is IMO one of the fundamental characteristics of a good RESTful design.

With the example proposed below, suppose the client wants to change the cart item quantity from 4 to 10. Calling "add":6 twice would increase the quantity to 16. (Another way to think about this is that you have implicitly introduced shared state between client and server: when the client calls "add":6, it is implicitly assuming the current state of the quantity is 4).

A better design for a simple case is (in pseudocode):

GET => quantity
quantity += 6
PUT quantity

Now, this still assumes that quantity doesn't change on the server in between the GET and the PUT, which may be true in this case. But if the quantity could change -- for example, a bank account where there are lots of possible sources for account credits and debits -- you need something a bit more sophisticated. For example, instead of ADD and REMOVE methods, you have a CHANGE method, and "add 6" becomes something like this:

GET => quantity

POST /cart-items/1/change_quantity

{

   "from": quantity
   "to": quantity+6

}

So now your POST is a transaction, and if the quantity has changed in the interim you will get an appropriate return code, which you will handle in the client.

--CZ

[Kijana Woodard]

You can make add & remove idempotent by including a "request id".

I'd probably prefer such a scheme such that diffs are posted to form a log. Individual cart items wouldn't be individually addressable.

My question is whether *your* users expect that or whether the expect to be able to simply set the quantity.

--

[Jørn Wildt]

Here is another (idempotent) approach. Start with a GET of the chart item. This should return, among other values, the quantity of the item. It should also return an ETag header. Now change the quantity and PUT back the whole item together with an if-match header with the previous ETag value. See for instance http://fideloper.com/etags-and-optimistic-concurrency-control for some more info.

If you need more specific knowledge about the operation on the server side then PUT doesn't help you and should go for some of the more message/command oriented approaches mentioned earlier.

/Jørn

--
/Jørn

[Jeferson Daniel]

It is a very abstract example, the GET method would be something like:

GET /cart-items/1

{

   "product": {..}

   "quantity": 4

}

In pratice, the client will expect to simply put the quantity value. But i am looking for approachs when dealing with increments and decrements. The "Request Id" approach looks good for me.