From 5b3121507a4e2ca81ed0b5fb72a23049a52ed135 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Mon, 12 Feb 2018 20:38:30 +0100 Subject: first sync draft --- api-sync.rst | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 api-sync.rst diff --git a/api-sync.rst b/api-sync.rst new file mode 100644 index 00000000..be40e752 --- /dev/null +++ b/api-sync.rst @@ -0,0 +1,166 @@ +.. + This file is part of GNU TALER. + Copyright (C) 2018 Taler Systems SA + + TALER is free software; you can redistribute it and/or modify it under the + terms of the GNU General Public License as published by the Free Software + Foundation; either version 2.1, or (at your option) any later version. + + TALER is distributed in the hope that it will be useful, but WITHOUT ANY + WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR + A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + + You should have received a copy of the GNU Lesser General Public License along with + TALER; see the file COPYING. If not, see + + @author Christian Grothoff + +.. _sync-api: + +============================================= +Wallet Backup and Synchronization Service API +============================================= + +-------------------------- +Receiving Terms of Service +-------------------------- + +.. http:get:: /terms + + Obtain the terms of service provided by the storage service. + + + **Response:** + + Returns a `SyncTermsOfServiceResponse`_. + + .. _SyncTermsOfServiceResponse: + .. _tsref-type-SyncTermsOfServiceResponse: + .. code-block:: tsref + + interface SyncTermsOfServiceResponse { + // maximum wallet database backup size supported + storage_limit_in_megabytes: number; + + // maximum number of sync requests per day (per account) + daily_sync_limit: number; + + // how long after an account (or device) becomes dormant does the + // service expire the respective records? + inactive_expiration: relative-time; + + // Fee for an account, per year. + annual_fee: Amount; + + // Maximum liability the service assumes for lost wallet data + liability: Amount; + } + + +.. _sync: + +.. http:get:: /$WALLET-KEY + + Download latest version of the wallet database. Note that this + operation should only be used the first time. Later, the wallet + should always use POST. + + **Response** + + :status 200 OK: + The body contains the current version of the wallet's + database as known to the server. + + :status 204 No content: + This is a fresh account, no previous wallet data exists at + the server. + + :status 429 Too many requests: + This account has exceeded daily thresholds for the number of + requests. Try again later. + + + .. note:: + + 200 OK responses include an HTTP header + "X-Taler-Sync-Signature" with the signature of the + wallet from the orginal upload, and an + "X-Taler-Sync-Previous" with the version that was + being updated (unless this is the first revision). + +.. http:post:: /$WALLET-KEY + + Upload a new version of the wallet's database, or download the + latest version. The request must include the "Expect: 100 Continue" + header. The client must wait for "100 Continue" before proceeding + with the upload, regardless of the size of the upload. + + **Request** + + The request must include a "If-Match" (FIXME: correct?) + header indicating the latest version of the wallet's database + known to the client. If the server knows a more recent version, + it will respond with a 409 conflict and return the server's + version in the response. The client must then merge the two + versions before retrying the upload. + + The request must also include an "X-Taler-Sync-Signature" + signing the "If-Match" SHA-512 value and the SHA-512 hash + of the body with the wallet private key. The SHA-512 hash + of the body must also be given in an "E-tag" header of the + request (so that the signature can be verified before the + upload is allowed to proceed). + + The uploaded body must have at least 32 bytes of payload. + + **Response** + + :status 204 No content: + The transfer was successful, and the server has registered + the new version. + + :status 304 Not modified: + The server is already aware of this version of the wallet. + Returned before 100 continue to avoid upload. + + :status 402 Payment required: + The synchronization service requires payment before the + account can continue to be used. + + :status 401 Not authorized: + The signature is invalid or missing (or body does not match). + + :status 409 Conflict: + The server has a more recent version than what is given + in "If-Match". The more recent version is returned. The + client should merge the two versions and retry using the + given response's "E-Tag" in the next attempt in "If-Match". + + :status 410 Gone: + The backup service has closed operations. The body will + contain the latest version still available at the server. + The user should be urged to find another provider. + + :status 411 Length required: + The client must specify the content-length before + attempting upload. + + :status 413 Payload too large: + The requested upload exceeds the quota for the account. + + :status 429 Too many requests: + This account has exceeded daily thresholds for the number of + requests. Try again later. + + .. note:: + + Responses with a body include an HTTP header + "X-Taler-Sync-Signature" with the signature of the + wallet from the orginal upload, and an + "X-Taler-Sync-Previous" with the version that was + being updated (unless this is the first revision). + + + + + -- cgit v1.2.3