From a50686a07cedc9ab0a800b4897757b24d593c444 Mon Sep 17 00:00:00 2001 From: Damyan Ivanov Date: Wed, 9 Feb 2022 06:17:50 +0000 Subject: [PATCH] document adding and modifying list items --- doc/protocol.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) 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. -- 2.39.2