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