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`: the list URI. Referred to as `/list/$list_id` below. The part after
  19      the last `/` (`$list_id`) is an integer that is unique among all shopping
  20      lists
  21    - `name`: list name as entered by users
  22  - `lists_version`: a number that is incremented by 1 each time the list of
  23    shopping lists changes. Changes include adding, removing and renaming a
  24    shopping list, but not changes to individual shopping list items.
  25
  26 GET /list/$list_id
  27 ------------------
  28
  29 Returns a JSON object with the following keys:
  30
  31  - `items`: a list of shopping list item objects with keys:
  32    - `uri`: the URI of the individual list item (refered to as
  33      `/list/$list_id/$item_id` below. The part after the last `/` (`$list_id`)
  34      is a positive integer that is unique amont the items in the shopping list.
  35    - `description`: item description
  36    - `done`: a boolean flag marking the item as done
  37  - `version`: a number that is incremented by 1 each time the list items
  38    change. Changes include adding, removing, renaming and marking a shopping
  39    list item as done or pending.
  40  - `lists_version`: the current version of the list of shopping lists
  41
  42 GET /list/$list_id/$item_id
  43 ---------------------------
  44
  45 Returns a JSON object with the following keys:
  46
  47  - `description`: the description of the shopping list item
  48  - `done`: a boolean flag marking the item as done
  49  - `list_version`: the current version of the list
  50  - `lists_version`: the current version of the list of shopping lists
  51
  52 POST /list
  53 ----------
  54
  55 Creates a new list. Request body is a JSON object with the following keys:
  56
  57  - `name`: list name as entered by the user
  58
  59 Response is a JSON object with the following keys:
  60
  61  - `uri`: the URI of the list (`/list/$list_id`)
  62  - `version`: the initial version of the list
  63  - `lists_version`: the version of the list of lists
  64
  65 PUT /list/$list_id
  66 ------------------
  67
  68 Modifies a list. Request body is a JSON object with the following keys:
  69
  70  - `name`: new list name
  71  - `version`: current list version as known by the client
  72
  73 Successful (HTTP status 200) response is a JSON object with the following keys:
  74
  75  - `version`: the curre version of the list
  76  - `lists_version`: the new version of the list of lists
  77
  78 Possible error responses:
  79
  80  - HTTP status 409 (conflict): the list has been modified
  81    Suggested client action is to fetch a fresh copy of the list data, present
  82    the differences to the user and either cancel the request and keep the newly
  83    fetched data as current, or re-submit the change using the fresh version
  84    number.
  85
  86 DELETE /list/$list_id
  87 ---------------------
  88
  89 Deletes the list. No request body. Always succeeds, even if the list doesn't
  90 exist server-side, in which case the `lists_version` isn't changed.
  91
  92 Returns JSON object with the following keys:
  93
  94  - `lists_version`: the new version of the list of lists.
  95
  96 POST /list/$list_id
  97 -------------------
  98
  99 Adds an item to the shopping list. Request body is a JSON object with the
 100 following keys:
 101
 102  - `description`: the description of the new shopping list item
 103  - `done`: (boolean) the done state
 104
 105 Successful response is a JSON object with the following keys:
 106
 107  - `uri`: the URI of the newly added shopping list item
 108  - `version`: version of the item
 109  - `list_version`: version of the containing list
 110  - `lists_version`: version of the list of lists
 111
 112 PUT /list/$list_id/$item_id
 113 ---------------------------
 114
 115 Modifies a shopping list item. Request body is a JSON object with the following
 116 keys:
 117
 118  - `description`: new item description
 119  - `done`: (boolean) desired item state
 120  - `version`: (required) the version of the item as known by the client
 121
 122 Successful response is a JSON object with the following keys:
 123
 124  - `version`: the new version of the item
 125  - `list_version`: the current version of the list
 126  - `lists_version`: the current version of the list of shopping lists
 127
 128 Possible error responses:
 129
 130  - HTTP status 409 (conflict): the item has been modified
 131    Suggested client action is to fetch a fresh copy of the item data, present
 132    the differences to the user and either cancel the request and keep the newly
 133    fetched data as current, or re-submit the change using the fresh version
 134    number.