spree/spree — pull request #3691 by Senjai (2013-09-09 04:35:39+00:00)
Title: Fixes #3293 - Change default endpoint behavior to reflect CRUD style.

This patch changes the default endpoint of the API's StockItemController to follow CRUD conventions for updating the resource. Per conversation in IRC it was discussed that the upate action on this controller would externally be inferred to "Update" the resource. Instead this action appends the inventory to the current count in the database which isn't explicitly stated to the end user.

I approached this issue as described in this PR and am open to feedback. Other thoughts of approaching it was to change the name of the param from count_on_hand to something more indicative to represent the fact that it is additive inventory, not declarative.

Creating a separate endpoint and action just to allow users to set the resource.

Implement as described, but create a separate endpoint and action to allow for the addition of inventory to prevent possible errors related to forgetting the append param.

This made sense because from a store owners perspective they would be in one of two scenarios:

1) A store holds inventory locally, and whenever it is notified of a shipment en route that third party can add that inventory to their inventory as it is on arrival e.g. additive inventory

2) A store holds inventory externally, e.g. in a shared warehouse, the operator of that warehouse would then have complete control of the "inventory on hand" and it would make sense to be able to control the "count on hand"

If case #1 was the most predominantly used, the fact remains that keeping the ability to add on a bare update function doesn't seem very CRUDy. The third parties that would update this information also fit into a niche. Usually the store wouldn't update their inventory until they receive it from their provider, at this point the inventory would unlikely be additive via an API and instead would be on the actual application by the receiver.

This is my first ever open source contribution, so if I'm blatantly off course please let me know and how I should improve in the future.