document adding and modifying list items

diff --git a/doc/protocol.md b/doc/protocol.md
index 28e978157c441632f88e117ffdb28f3cf5336e67..ae7bad53862528ed15f5a9343393953ee9c0c692 100644 (file)
--- a/doc/protocol.md
+++ b/doc/protocol.md
@@ -88,3 +88,43 @@ exist server-side, in which case the `lists_version` isn't changed.
 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.