initial draft of communication protocol

diff --git a/doc/protocol.md b/doc/protocol.md
new file mode 100644 (file)
index 0000000..28e9781
--- /dev/null
+++ b/doc/protocol.md
@@ -0,0 +1,90 @@
+Lazy Shopping List protocol
+===========================
+
+GET /
+-----
+
+Returns a JSON object with the following keys:
+
+ - `lists`: URI for the list of shopping lists available. Referred to as
+   `/list` below.
+
+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_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.
+
+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
+   - `done`: a boolean flag marking the item as done
+ - `version`: a number that is incremented by 1 each time the list items
+   change. Changes include adding, removing, renaming and marking a shopping
+   list item as done or pending.
+ - `lists_version`: the current version of the list of shopping lists
+
+GET /list/$list_id/$item_id
+---------------------------
+
+Returns a JSON object with the following keys:
+
+ - `description`: the description of the shopping list item
+ - `done`: a boolean flag marking the item as done
+ - `list_version`: the current version of the list
+ - `lists_version`: the current version of the list of shopping lists
+
+POST /list
+----------
+
+Creates a new list. Request body is a JSON object with the following keys:
+
+ - `name`: list name as entered by the user
+
+Response is a JSON object with the following keys:
+
+ - `uri`: the URI of the list (`/list/$list_id`)
+ - `version`: the initial version of the list
+ - `lists_version`: the version of the list of lists
+
+PUT /list/$list_id
+------------------
+
+Modifies a list. Request body is a JSON object with the following keys:
+
+ - `name`: new list name
+ - `version`: current list version as known by the client
+
+Successful (HTTP status 200) response is a JSON object with the following keys:
+
+ - `version`: the curre version of the list
+ - `lists_version`: the new version of the list of lists
+
+Possible error responses:
+
+ - HTTP status 409 (conflict): the list has been modified
+   Suggested client action is to fetch a fresh copy of the list 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.
+
+DELETE /list/$list_id
+---------------------
+
+Deletes the list. No request body. Always succeeds, even if the list doesn't
+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.