first sync draft

1 files changed, 166 insertions, 0 deletions

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 <http://www.gnu.org/licenses/>
+
+  @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).
+
+
+    
+
+