api/pageplace.bosh-bosh-rest-sync-data.rst

   1 =======================================================
   2 ``PATCH https://bosh.pageplace.de/bosh/rest/sync-data``
   3 =======================================================
   4 Send changes to the server and get changes since last sync back.
   5 This is the main API method for synchronization.
   6
   7 Part of the `Sync process`_.
   8
   9 Request
  10 =======
  11 Header
  12   ``t_auth_token``
  13     OAuth token obtained from `POST https://thalia.de/auth/oauth2/token`_.
  14
  15     Example: ``eyJhbGciOiJSUzI1NiJ9.eyJhdWRpZW5jZSI6InRyZWFkZXJ2aXNpb24zIiw...``
  16   ``Content-Type``
  17     ``application/json; charset=UTF-8``
  18   ``Accept``
  19     ``application/json; charset=UTF-8``
  20   ``reseller_id``
  21     Example: ``3``
  22   ``hardware_id``
  23     Example: ``665fc389ef4e47258c5db9fa7821bd19``
  24   ``client_type``
  25     Example: ``TOLINO_VISION_3``
  26 GET parameters
  27   ``paths``
  28     Example: ``publications``
  29
  30     FIXME: What else?
  31 Request body parameters
  32   ``revision``
  33     ``revision`` of last sync response.
  34
  35     ``null`` when it is the first sync ever for this device.
  36   ``patches``
  37     Array of changes.
  38
  39     No data to sync: Empty array ``[]``.
  40
  41     Changes are objects with the following properties:
  42
  43     ``op``
  44       The patch operation: ``add``, ``replace``, ``remove``
  45
  46       ``replace`` is used to update the reading position.
  47
  48     ``path``
  49       Example: ``/publications/DT0400.9783739673417_A27522964/bookmark/606779074``
  50
  51       Consists of several parts:
  52
  53       1. The prefix seems always to be ``/publications/``.
  54       2. A publication ID ``DT0400.9783739673417_A27522964``
  55       3. The type that is created/updated/deleted:
  56
  57          - ``bookmark`` is the reading position
  58          - ``dogears`` when bookmarking a page in the e-book
  59          - ``comments`` when highlighting/marking some text or adding a note
  60       4. FIXME: Some ID.
  61
  62     ``value``
  63       Details of the change. Properties depend on the type.
  64
  65       ``modified``
  66         Time when this action was done in milliseconds. Type: Integer.
  67
  68         Example: ``1612127562802``
  69       ``position``
  70         File name of the chapter in the epub,
  71         plus specific data in the anchor. Type: String.
  72
  73         Example: ``OEBPS/caterina-di-montebasso-das-relikt_0.html#point(/1/2/1/11/1:114)``
  74       ``revision``
  75         FIXME. Type: String.
  76
  77         FIXME: Can be ``null``. When?
  78
  79         The patch part revisions share some prefix with the patch revision,
  80         but are a bit longer.
  81         Seem to be base64-encoded, since the often (always?) have ``==`` at the end.
  82
  83         In the response, the patch part revisions also share some prefix with
  84         the new server revision.
  85
  86         Example: ``Lmu7TngaxhKWHdv2FFktQNcGFPmnOshpANcqFEx7udpEDvQDdiq93W8ryZG4oSfm9D9sp2Aowkhu/1wg8qj4PglnxUFM96DOLgZMd9NVnTByM/ZG1vgkHHCrqwpA/7bO67OjTjo1TLKVL442Lx3sGw==``
  87       ``progress``
  88         Reading progress in the ranging from 0-1. Type: Float.
  89
  90         Only for ``bookmark`` (reading position) patches.
  91
  92         Example: ``0.41666666``
  93       ``currentPosition``
  94         Current page number. Type: String.
  95
  96         Only for ``bookmark`` (reading position) patches.
  97
  98         Example: ``"5"``
  99       ``lastPosition``
 100         Last page number in the book. Type: String
 101
 102         Only for ``bookmark`` (reading position) patches.
 103
 104         Example: ``"12"``
 105       ``transientId``
 106         FIXME. Type: String.
 107
 108         Only when ``op=add`` on ``dogears`` (bookmark) and ``comments``.
 109
 110         Example: ``"3"``
 111       ``name``
 112         Text on the bookmarked page. Type: String.
 113
 114         Only for ``dogears`` (bookmark) add+remove operations.
 115       ``text``
 116         Highlighted text. Type: String
 117
 118         Only for ``comments`` (highlight/note) add+remove operations.
 119       ``startPosition``
 120         Start of highlighted text. Type: String.
 121
 122         Only for ``comments`` (highlight/note) add+remove operations.
 123
 124         Example: ``OEBPS/caterina-di-montebasso-das-relikt_0.html#point(/1/2/1/11/1:463)``
 125       ``endPosition``
 126         End of highlighted text. Type: String.
 127
 128         Only for ``comments`` (highlight/note) add+remove operations.
 129
 130         Example: ``OEBPS/caterina-di-montebasso-das-relikt_0.html#point(/1/2/1/11/1:682)``
 131       ``note``
 132         Manually entered text (note). Type: String.
 133
 134         Only for ``comments`` (note) add+remove operations.
 135
 136         Property does not appear for non-note highlights.
 137
 138         Example: ``Really?``
 139
 140
 141 When closing a book (going back to the book list), the current reading
 142 position is synchronized to the server - regardless if it changed.
 143 I removed that from the requests + responses to have cleaner examples.
 144
 145 The ``revision`` in the request is the ``revision`` the server returned
 146 in the last response.
 147
 148
 149 First sync request
 150 ------------------
 151 When nothing needs to be synchronized to the server, and nothing
 152 ever has been synchronized:
 153
 154 .. include:: pageplace.bosh-bosh-rest-sync-data.request-first.json
 155    :code:
 156
 157
 158 Set reading position
 159 --------------------
 160 Reading a page in the book and exiting back to the books list:
 161
 162 .. include:: pageplace.bosh-bosh-rest-sync-data.request-reading-position.json
 163    :code:
 164
 165
 166
 167 Response
 168 ========
 169 HTTP status code: ``200 OK``
 170
 171 When something changed, a new ``revision`` number is returned.
 172
 173 When synchronizing local changes to the server - and the server has no
 174 changes from other readers,
 175 the request is mirrored back in the response
 176 (only the revision number is updated).
 177
 178 The server first ingests the request's patch data into its database,
 179 and then calculates and returns the changes from the
 180 requests's ``revision`` number to the current revision.
 181 Those changes are returned in the response, together with the current
 182 latest revision number.
 183
 184 Same structure as the request data.
 185
 186
 187 Set reading position
 188 --------------------
 189 The "Set reading position" changes and a new revision is returned.
 190
 191 .. include:: pageplace.bosh-bosh-rest-sync-data.response-reading-position.json
 192    :code:
 193
 194
 195 Set a bookmark
 196 --------------
 197
 198 .. include:: pageplace.bosh-bosh-rest-sync-data.response-bookmark-set.json
 199    :code:
 200
 201
 202 Remove a bookmark
 203 -----------------
 204
 205 .. include:: pageplace.bosh-bosh-rest-sync-data.response-bookmark-remove.json
 206    :code:
 207
 208
 209 Add a highlight
 210 ---------------
 211
 212 .. include:: pageplace.bosh-bosh-rest-sync-data.response-highlight-add.json
 213    :code:
 214
 215
 216 Remove a highlight
 217 ------------------
 218
 219 .. include:: pageplace.bosh-bosh-rest-sync-data.response-highlight-remove.json
 220    :code:
 221
 222
 223 Add a note
 224 ----------
 225
 226 .. include:: pageplace.bosh-bosh-rest-sync-data.response-note-add.json
 227    :code:
 228
 229
 230 Remove a note
 231 -------------
 232
 233 .. include:: pageplace.bosh-bosh-rest-sync-data.response-note-remove.json
 234    :code:
 235
 236
 237 New bookmarks and comments
 238 --------------------------
 239 Example:
 240
 241 .. include:: pageplace.bosh-bosh-rest-sync-data.response-bookmarks-comments.json
 242    :code: