specing out bank's /history and authentication API

1 files changed, 62 insertions, 27 deletions

diff --git a/api/api-bank.rst b/api/api-bank.rst
index 231be383..1fec586f 100644
--- a/api/api-bank.rst
+++ b/api/api-bank.rst
@@ -47,11 +47,8 @@ request.
 
   interface BankDepositRequest {
 
-    // The username of the user calling this API.
-    username: string;
-
-    // Password of the user calling this API.
-    password: string;
+    // Authentication method used
+    auth: BankAuth;
 
     // JSON 'amount' object. The amount the caller wants to transfer
     // to the recipient's count
@@ -81,6 +78,24 @@ request.
 
   }
 
+
+.. _BankAuth:
+.. code-block:: tsref
+
+  interface BankAuth {
+
+    // authentication type.  Accepted values are:
+    // "basic", "digest", "token".
+    type: string; 
+    
+    // Optional object containing data consistent with the
+    // used authentication type.
+    data: Object;
+
+  }
+
+
+
 .. _BankIncomingError:
 .. code-block:: tsref
 
@@ -95,42 +110,62 @@ request.
 User API
 --------
 
-This API gets the user a list of his transactions, optionally limiting
+This API returns a list of his transactions, optionally limiting
 the number of results.
 
 .. http:post:: /history
 
 **Request:** The body of this request must have the format of a `HistoryRequest`_.
-TBD
 
-**Response**
-TBD
+**Response** JSON array of type `BankTransaction`_.
 
-.. _HistoryRequest:
+
+
+.. _BankTransaction:
 .. code-block:: tsref
 
-  interface HistoryRequest {
+  interface BankTransaction {
   
-    // The username of the user calling this API.
-    username: string;
+    // identification number of the record
+    row_id: number;
 
-    // Password of the user calling this API.
-    password: string;
+    // Date of the transaction
+    date: Timestamp;
 
-    // Row number identifier in the bank's database
-    // such that only rows with GREATER (meaning younger
-    // records) row number will be returned.
-    start: number;
+    // Amount transferred
+    amount: Amount;
 
-    // How many rows we want returned, at most.
-    delta: number;
+    // "-" if the transfer was outcoming, "+" if it was
+    // incoming.
+    sign: string;
+
+    // Bank account number of the other party
+    // involved in the transaction.
+    counterpart: number; 
+  
   }
 
---------
-Util API
---------
+..
+  The counterpart currently only points to the same bank as
+  the client using the bank.  A reasonable improvement is to
+  specify a bank URI too, so that Taler can run across multiple
+  banks.
 
-Whenever the user wants to know the bank account number of a public account,
-the following path returns a human readable HTML containing this information
+.. _HistoryRequest:
+.. code-block:: tsref
 
-  `/public-accounts/details?account=accountName`
+  interface HistoryRequest {
+  
+    // Authentication method used
+    auth: BankAuth;
+
+    // Only records with row id LESSER than `start' will
+    // be returned.  NOTE, smaller row ids denote older db
+    // records.  If this value equals zero, then the youngest
+    // `delta' rows are returned.
+    start: number;
+
+    // Optional value denoting how many rows we want receive.
+    // If not given, then it defaults to 10.
+    delta: number;
+  }