protocol change: supply list name in the list of lists

[lsl.git] / doc / protocol.md

diff --git a/doc/protocol.md b/doc/protocol.md
index 28e978157c441632f88e117ffdb28f3cf5336e67..e0cf516c6658b533acb312c1ec5aa69153fc7e58 100644 (file)
--- a/doc/protocol.md
+++ b/doc/protocol.md
@@ -14,8 +14,9 @@ GET /list
 
 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`: tjhe list URIs. Referred to as `/list/$list_id` below.
+   - `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.
@@ -25,7 +26,6 @@ GET /list/$list_id
 
 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
    - `description`: item description
@@ -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.