summaryrefslogtreecommitdiff
path: root/api-sync.rst
blob: be40e75287e2650d5ba624fb8c2935e8db8d7b2a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
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).