[taler-docs] branch master updated: bank API split, bank access API docs

[gnunet]

This is an automated email from the git hooks/post-receive script.

dold pushed a commit to branch master
in repository docs.

The following commit(s) were added to refs/heads/master by this push:
     new 0e650e7  bank API split, bank access API docs
0e650e7 is described below

commit 0e650e78865fef95adc61021dabce4f294c83ad4
Author: Florian Dold <address@hidden>
AuthorDate: Mon Feb 17 20:34:20 2020 +0100

    bank API split, bank access API docs
---
 _exts/typescriptdomain.py                       |   2 +-
 core/api-bank-access.rst                        | 143 ++++++++++++++++++++++++
 core/{api-bank.rst => api-bank-integration.rst} |  23 +---
 core/api-common.rst                             |   8 ++
 core/index.rst                                  |   3 +-
 libeufin/api-nexus.rst                          |   2 +
 6 files changed, 159 insertions(+), 22 deletions(-)

diff --git a/_exts/typescriptdomain.py b/_exts/typescriptdomain.py
index 73a5ada..b0780ea 100644
--- a/_exts/typescriptdomain.py
+++ b/_exts/typescriptdomain.py
@@ -388,7 +388,7 @@ class LinkingHtmlFormatter(HtmlFormatter):
         if tok_getprop(tok, "is_identifier"):
             if xref.startswith('"'):
                 return value
-            if xref in ("number", "object", "string", "boolean", "any", 
"true", "false"):
+            if xref in ("number", "object", "string", "boolean", "any", 
"true", "false", "null"):
                 return value
 
         if xref is None:
diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst
new file mode 100644
index 0000000..757a2e3
--- /dev/null
+++ b/core/api-bank-access.rst
@@ -0,0 +1,143 @@
+..
+  This file is part of GNU TALER.
+
+  Copyright (C) 2014-2020 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 General Public License for more details.
+
+  You should have received a copy of the GNU General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Florian Dold
+
+=============================
+Taler Bank Account Access API
+=============================
+
+This chapter describes the API that the GNU Taler demonstrator bank offers to 
access accounts.
+
+This API differes from the "Bank Integration API" in that it provides advanced 
API access to accounts, as opposed
+to enabling wallets to withdraw with an better user experience ("tight 
integration").
+
+
+.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/balance
+
+  Request the current balance of an account.
+
+  **Response**
+
+  **Details**
+
+  .. ts:def:: BankAccountBalanceResponse
+
+    interface BankAccountBalanceResponse {
+      // Amount with plus or minus sign, representing the current
+      // available account balance.
+      balance: SignedAmount;
+    }
+
+
+.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
+
+  Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
+
+  **Response**
+
+  **Details**
+
+  .. ts:def:: BankAccountCreateWithdrawalResponse
+
+    interface BankAccountCreateWithdrawalResponse {
+      // ID of the withdrawal, can be used to view/modify the withdrawal 
operation
+      withdrawal_id: string;
+
+      // URI that can be passed to the wallet to initiate the withdrawal
+      taler_withdraw_uri: string;
+    }
+
+
+.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
+
+  Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
+
+  **Request**
+
+  .. ts:def:: BankAccountCreateWithdrawalRequest
+
+    interface BankAccountCreateWithdrawalRequest {
+      // Amount to withdraw
+      amount: Amount;
+    }
+
+  **Response**
+
+  .. ts:def:: BankAccountCreateWithdrawalResponse
+
+    interface BankAccountCreateWithdrawalResponse {
+      // ID of the withdrawal, can be used to view/modify the withdrawal 
operation
+      withdrawal_id: string;
+
+      // URI that can be passed to the wallet to initiate the withdrawal
+      taler_withdraw_uri: string;
+    }
+
+
+.. http:GET:: 
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}
+
+  Query the status of a withdrawal operation
+
+  **Response**
+
+  **Details**
+
+  .. ts:def:: BankAccountGetWithdrawalResponse
+
+    interface BankAccountGetWithdrawalResponse {
+      // Amount that will be withdrawn with this withdrawal operation
+      amount: Amount;
+
+      // Was the withdrawal aborted?
+      aborted: boolean;
+
+      // Has the withdrawal been confirmed by the bank?
+      // The wire transfer for a withdrawal is only executed once
+      // both confirmation_done is true and selection_done is true.
+      confirmation_done: boolean;
+
+      // Did the wallet select reserve details?
+      selection_done: boolean;
+
+      // Reserve public key selected by the exchange,
+      // only non-null if selection_done is 'true'
+      selected_reserve_pub: string | null;
+
+      // Exchange account selected by the exchange,
+      // only non-null if selection_done is 'true'
+      selected_exchange_account: string | null;
+    }
+
+
+.. http:POST:: 
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort
+
+  Abort a withdrawal operation.  Has no effect on an already aborted 
withdrawal operation.
+
+  :status 200 OK: The withdrawl operation has been aborted.  The response is 
an empty JSON object.
+  :status 409 Conflict:  The reserve operation has been confirmed previously 
and can't be aborted.
+
+
+.. http:POST:: 
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm
+
+  Confirm a withdrawal operation.  Has no effect on an already confirmed 
withdrawal operation.
+
+  **Response**
+
+  :status 200 OK: The withdrawl operation has been confirmed.  The response is 
an empty JSON object.
+  :status 409 Conflict:  The reserve operation has been aborted previously and 
can't be confirmed.
+
+
diff --git a/core/api-bank.rst b/core/api-bank-integration.rst
similarity index 91%
rename from core/api-bank.rst
rename to core/api-bank-integration.rst
index 0b7b971..f63fe77 100644
--- a/core/api-bank.rst
+++ b/core/api-bank-integration.rst
@@ -17,9 +17,9 @@
   @author Marcello Stanisci
   @author Christian Grothoff
 
-==============
-Taler Bank API
-==============
+==========================
+Taler Bank Integration API
+==========================
 
 This chapter describe the APIs that banks need to offer towards Taler wallets
 to tightly integrate with GNU Taler.
@@ -156,20 +156,3 @@ for the withdrawal operation (the ``wopid``) to interact 
with the withdrawal ope
       confirm_transfer_url?: string;
     }
 
-
-------------
-Testing APIs
-------------
-
-The following APIs are exposed by some bank API implementations **for 
testing** as part
-of the wallet's integration tests.
-
-.. warning::
-
-  These APIs **must not** be offered by any production systems.
-
-.. http:post:: ${BANK_API_BASE_URL}/testing/register
-
-.. http:post:: ${BANK_API_BASE_URL}/testing/withdraw
-
-.. http:post:: ${BANK_API_BASE_URL}/testing/withdraw-uri
diff --git a/core/api-common.rst b/core/api-common.rst
index 9584f24..a7ebe3a 100644
--- a/core/api-common.rst
+++ b/core/api-common.rst
@@ -335,6 +335,14 @@ Internally, amounts are parsed into the following object:
   }
 
 
+An amount that is prefixed with a ``+`` or ``-`` character is also used in 
certain contexts.
+When no sign is present, the amount is assumed to be positive.
+
+.. ts:def:: SignedAmount
+
+  type SignedAmount = string;
+
+
 --------------
 Binary Formats
 --------------
diff --git a/core/index.rst b/core/index.rst
index 8c86262..95037d4 100644
--- a/core/index.rst
+++ b/core/index.rst
@@ -35,7 +35,8 @@ interfaces between the core components of Taler.
   api-wire
   api-merchant
   api-auditor
-  api-bank
+  api-bank-integration
+  api-bank-access
   wireformats
   api-sync
   taler-uri
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index fb02858..745182c 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -69,6 +69,7 @@ Low-level EBICS API
 
 
   .. ts:def:: NexusEbicsBackupResponse
+
     interface NexusEbicsBackupResponse {
       
       // The three passphrase-protected private keys in the PKCS#8 format
@@ -89,6 +90,7 @@ Low-level EBICS API
   "{id}" account, and fails if it exists already.
 
   .. ts:def:: NexusEbicsRestoreBackupRequest
+
     interface NexusEbicsRestoreBackupRequest {
       
       // passphrase to decrypt the keys

-- 
To stop receiving notification emails like this one, please contact
address@hidden.