Returns a JSON object with the following keys:
- - `lists`: a list of shopping list URIs. Referred to as `/list/$list_id`
- below.
+ - `lists`: a list of objects with the following keys:
+ - `uri`: the list URI. Referred to as `/list/$list_id` below. The part after
+ the last `/` (`$list_id`) is an integer that is unique among all shopping
+ lists
+ - `name`: list name as entered by users
- `lists_version`: a number that is incremented by 1 each time the list of
shopping lists changes. Changes include adding, removing and renaming a
shopping list, but not changes to individual shopping list items.
Returns a JSON object with the following keys:
- - `name`: list name, as entered by users
- `items`: a list of shopping list item objects with keys:
- - `uri`: the URI of the individual list item
+ - `uri`: the URI of the individual list item (refered to as
+ `/list/$list_id/$item_id` below. The part after the last `/` (`$list_id`)
+ is a positive integer that is unique amont the items in the shopping list.
- `description`: item description
- `done`: a boolean flag marking the item as done
- `version`: a number that is incremented by 1 each time the list items
Successful (HTTP status 200) response is a JSON object with the following keys:
- - `version`: the curre version of the list
+ - `version`: the current version of the list
- `lists_version`: the new version of the list of lists
Possible error responses:
Returns JSON object with the following keys:
- `lists_version`: the new version of the list of lists.
+
+POST /list/$list_id
+-------------------
+
+Adds an item to the shopping list. Request body is a JSON object with the
+following keys:
+
+ - `description`: the description of the new shopping list item
+ - `done`: (boolean) the done state
+
+Successful response is a JSON object with the following keys:
+
+ - `uri`: the URI of the newly added shopping list item
+ - `version`: version of the item
+ - `list_version`: version of the containing list
+ - `lists_version`: version of the list of lists
+
+PUT /list/$list_id/$item_id
+---------------------------
+
+Modifies a shopping list item. Request body is a JSON object with the following
+keys:
+
+ - `description`: new item description
+ - `done`: (boolean) desired item state
+ - `version`: (required) the version of the item as known by the client
+
+Successful response is a JSON object with the following keys:
+
+ - `version`: the new version of the item
+ - `list_version`: the current version of the list
+ - `lists_version`: the current version of the list of shopping lists
+
+Possible error responses:
+
+ - HTTP status 409 (conflict): the item has been modified
+ Suggested client action is to fetch a fresh copy of the item data, present
+ the differences to the user and either cancel the request and keep the newly
+ fetched data as current, or re-submit the change using the fresh version
+ number.