doc/protocol.md

   1 Lazy Shopping List protocol
   2 ===========================
   3
   4 GET /
   5 -----
   6
   7 Returns a JSON object with the following keys:
   8
   9  - `lists`: URI for the list of shopping lists available. Referred to as
  10    `/list` below.
  11
  12 GET /list
  13 ----------
  14
  15 Returns a JSON object with the following keys:
  16
  17  - `lists`: a list of shopping list URIs. Referred to as `/list/$list_id`
  18    below.
  19  - `lists_version`: a number that is incremented by 1 each time the list of
  20    shopping lists changes. Changes include adding, removing and renaming a
  21    shopping list, but not changes to individual shopping list items.
  22
  23 GET /list/$list_id
  24 ------------------
  25
  26 Returns a JSON object with the following keys:
  27
  28  - `name`: list name, as entered by users
  29  - `items`: a list of shopping list item objects with keys:
  30    - `uri`: the URI of the individual list item
  31    - `description`: item description
  32    - `done`: a boolean flag marking the item as done
  33  - `version`: a number that is incremented by 1 each time the list items
  34    change. Changes include adding, removing, renaming and marking a shopping
  35    list item as done or pending.
  36  - `lists_version`: the current version of the list of shopping lists
  37
  38 GET /list/$list_id/$item_id
  39 ---------------------------
  40
  41 Returns a JSON object with the following keys:
  42
  43  - `description`: the description of the shopping list item
  44  - `done`: a boolean flag marking the item as done
  45  - `list_version`: the current version of the list
  46  - `lists_version`: the current version of the list of shopping lists
  47
  48 POST /list
  49 ----------
  50
  51 Creates a new list. Request body is a JSON object with the following keys:
  52
  53  - `name`: list name as entered by the user
  54
  55 Response is a JSON object with the following keys:
  56
  57  - `uri`: the URI of the list (`/list/$list_id`)
  58  - `version`: the initial version of the list
  59  - `lists_version`: the version of the list of lists
  60
  61 PUT /list/$list_id
  62 ------------------
  63
  64 Modifies a list. Request body is a JSON object with the following keys:
  65
  66  - `name`: new list name
  67  - `version`: current list version as known by the client
  68
  69 Successful (HTTP status 200) response is a JSON object with the following keys:
  70
  71  - `version`: the curre version of the list
  72  - `lists_version`: the new version of the list of lists
  73
  74 Possible error responses:
  75
  76  - HTTP status 409 (conflict): the list has been modified
  77    Suggested client action is to fetch a fresh copy of the list data, present
  78    the differences to the user and either cancel the request and keep the newly
  79    fetched data as current, or re-submit the change using the fresh version
  80    number.
  81
  82 DELETE /list/$list_id
  83 ---------------------
  84
  85 Deletes the list. No request body. Always succeeds, even if the list doesn't
  86 exist server-side, in which case the `lists_version` isn't changed.
  87
  88 Returns JSON object with the following keys:
  89
  90  - `lists_version`: the new version of the list of lists.