From: Damyan Ivanov <dmn@debian.org>
Date: Wed, 9 Feb 2022 06:17:50 +0000 (+0000)
Subject: document adding and modifying list items
X-Git-Url: https://git.ktnx.net/?a=commitdiff_plain;h=a50686a07cedc9ab0a800b4897757b24d593c444;p=lsl.git

document adding and modifying list items
---

diff --git a/doc/protocol.md b/doc/protocol.md
index 28e9781..ae7bad5 100644
--- 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.