Add basically API documentation

docs/api/sync.md

@@ -0,0 +1,117 @@
+# /sync
+
+This endpoint is used by clients for syncing.
+
+## the sync process
+
+- the client pushes all actions (eventually in chunks)
+  - all actions are numbered so that the server can ignore it if the client sends an action multiple times (e.g. due to connectivity issues)
+  - in case something goes wrong, the server asks the client to do a full query when pulling the status the next time
+- the client pulls the status
+  - the client sends a summary of the current status
+  - the server does not send the data which the client already knows
+- in case the client is unauthorized, then the client checks against /sync/is-device-removed
+  - if it tells the client that it was really removed, then the client resets itself
+
+## possible sync triggers
+
+- periodically/ by the time (e.g. every hour, not all 10 seconds)
+- the [websocket](./websocket.md) for syncing as soon as something was changed by an other client
+- changes/ actions at the client itself
+
+## POST /sync/push-actions
+
+Use this to sync actions to the server.
+
+### request
+
+see [this JSON schema](../schema/clientpushchangesrequest.md)
+
+the encoded actions are stringified JSON objects of one of this schemes:
+- [serialized app logic action](../schema/serializedapplogicaction.md)
+- [serialized parent action](../schema/serializedparentaction.md)
+- [serialized child action](../schema/serializedchildaction.md)
+
+The request must not contain more than 50 actions. The request may contain less than 50
+actions.
+
+The sequence numbers must be a increasing sequence per device.
+
+#### integrity
+
+The integrity field of a action may have got one of the following values:
+
+- an empty string when no user authentication is required/ for app logic actions (e.g. incrementing the used time)
+- the string ``device`` in case of parent actions if a parent is assigned to the device and asking for the password was disabled
+- ``sha512(sequence number as string with the base 10 + the device id as string + the hash of the user password using the second salt as string + the encoded action as string)`` for parent and child actions
+
+In case of a invalid integrity value, the action is ignored and the client is told to do a full sync
+
+### response
+
+On a invalid request body: HTTP status code 400 Bad request
+
+On a invalid auth token: HTTP status code 401 Unauthorized
+
+On success: JSON object with the property ``shouldDoFullSync`` - example: ``{"shouldDoFullSync": false}``
+
+### error handling
+
+If a action has got a invalid ``integrity`` or ``encodedAction``, then only this action
+is ignored and ``shouldDoFullSync`` will be true.
+
+## POST /sync/pull-status
+
+Use this to pull the current status from the server.
+
+### request
+
+see [this JSON schema](../schema/clientpullchangesrequest.md)
+
+### response
+
+On a invalid request body: HTTP status code 400 Bad request
+
+On a invalid auth token: HTTP status code 401 Unauthorized
+
+On success: see [this JSON schema](../schema/serverdatastatus.md)
+
+## POST /sync/report-removed
+
+Use this to report that TimeLimit is/ was reset.
+
+### request
+
+see [this JSON schema](../schema/requestwithauthtoken.md)
+
+### response
+
+On a invalid request body: http status code 400 Bad request
+
+On a invalid/ unknown auth token: http status code 500 Internal Server Error
+
+On success: ``{"ok": true}``
+
+### error handling
+
+If a removed device reports that it is removed, then it is ignored and handled
+as success.
+
+## POST /sync/is-device-removed
+
+Use this to check if the device was removed.
+
+Background: This checks if the auth token is in a list of known old auth tokens.
+This ensures that an empty database at the server does not trigger the client reset feature.
+
+### request
+
+see [this JSON schema](../schema/requestwithauthtoken.md)
+
+### response
+
+On a invalid request body: http status code 400 bad request
+
+object with the property ``isDeviceRemoved`` of the type boolean
+
+example response: ``{"isDeviceRemoved": false}``