X-Git-Url: https://git.ktnx.net/?a=blobdiff_plain;f=doc%2Fprotocol.md;h=25ab284d2067f48cc2937603799867ce70b67c6e;hb=871141f37497c7de80ab25708900364e8df204fa;hp=28e978157c441632f88e117ffdb28f3cf5336e67;hpb=ebeb77d600281a9c7632077c108c33cf1d2fafd4;p=lsl.git

diff --git a/doc/protocol.md b/doc/protocol.md
index 28e9781..25ab284 100644
--- a/doc/protocol.md
+++ b/doc/protocol.md
@@ -14,8 +14,11 @@ 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`: 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.
@@ -25,9 +28,10 @@ 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
+   - `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
@@ -68,7 +72,7 @@ Modifies a list. Request body is a JSON object with the following keys:
 
 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:
@@ -88,3 +92,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.