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 objects with the following keys:
  18    - `uri`: tjhe list URIs. Referred to as `/list/$list_id` below.
  19    - `name`: list name as entered by users
  20  - `lists_version`: a number that is incremented by 1 each time the list of
  21    shopping lists changes. Changes include adding, removing and renaming a
  22    shopping list, but not changes to individual shopping list items.
  23
  24 GET /list/$list_id
  25 ------------------
  26
  27 Returns a JSON object with the following keys:
  28
  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.
  91
  92 POST /list/$list_id
  93 -------------------
  94
  95 Adds an item to the shopping list. Request body is a JSON object with the
  96 following keys:
  97
  98  - `description`: the description of the new shopping list item
  99  - `done`: (boolean) the done state
 100
 101 Successful response is a JSON object with the following keys:
 102
 103  - `uri`: the URI of the newly added shopping list item
 104  - `version`: version of the item
 105  - `list_version`: version of the containing list
 106  - `lists_version`: version of the list of lists
 107
 108 PUT /list/$list_id/$item_id
 109 ---------------------------
 110
 111 Modifies a shopping list item. Request body is a JSON object with the following
 112 keys:
 113
 114  - `description`: new item description
 115  - `done`: (boolean) desired item state
 116  - `version`: (required) the version of the item as known by the client
 117
 118 Successful response is a JSON object with the following keys:
 119
 120  - `version`: the new version of the item
 121  - `list_version`: the current version of the list
 122  - `lists_version`: the current version of the list of shopping lists
 123
 124 Possible error responses:
 125
 126  - HTTP status 409 (conflict): the item has been modified
 127    Suggested client action is to fetch a fresh copy of the item data, present
 128    the differences to the user and either cancel the request and keep the newly
 129    fetched data as current, or re-submit the change using the fresh version
 130    number.