Merge branch 'master' of git+ssh://git.taler.net/docs

2 files changed, 354 insertions, 238 deletions

diff --git a/libeufin/api-sandbox-future.rst b/libeufin/api-sandbox-future.rst
new file mode 100644
index 00000000..06dfc682
--- /dev/null
+++ b/libeufin/api-sandbox-future.rst
@@ -0,0 +1,135 @@
+Future Sandbox API
+##################
+
+Resources.
+^^^^^^^^^^
+
+Sandbox serves the following resources:
+
+ - Demobanks.
+ - Bank accounts.
+ - Subscribers.
+ - Transactions.
+ - Customers.
+ - Reports.
+
+The resources are subject to all CRUD operations, via by two
+types of users: the 'admin' and the customers.  The admin has
+rights on all of them.
+
+One of the main differences with the previous versions is the
+removal of the "/admin" initial component.  If the administrator
+authenticates for one operation, then this one is of type ``admin``:
+no need for a dedicated and extra URI path component.
+
+For example, mocking transactions in the system was a typical
+/admin-operation, but since transactions themselves are resources
+and any resource is subject to CRUD operations, then mocking one
+becomes just a ``C`` operation on the 'transactions' resources.  If
+a test case wants to simplify the authentication - by hard-coding
+the credentials, for example - before mocking one transaction, then
+it can impersonate the administrator.
+
+.. note::
+
+   ``POST``\ ing to an endpoint with a trailing ``$id`` means
+   modification of an existing resource.
+
+Demobanks
+^^^^^^^^^
+
+Demobanks are the main containers of all the other resources.
+They take configuration values, like the currency for example.
+
+.. http:get:: /admin/demobanks
+.. http:get:: /admin/demobanks/$id
+.. http:post:: /admin/demobanks
+.. http:post:: /admin/demobanks/$id
+.. http:delete:: /admin/demobanks/$id
+
+Bank accounts.
+^^^^^^^^^^^^^^
+
+Bank accounts collect money of customers and participate
+in transactions.
+
+The ``$base`` is one demobank, in the form ``/demobanks/$id``.
+That is due because a bank account must inherit some defaults
+from the demobank, like the currency.
+
+.. http:get:: $base/bankaccounts
+.. http:get:: $base/bankaccounts/$id
+.. http:post:: $base/bankaccounts
+.. http:post:: $base/bankaccounts/$id
+.. http:delete:: $base/bankaccounts/$id
+
+Subscribers.
+^^^^^^^^^^^^
+
+Subscribers are (optional) customers identities for protocols
+other than the native one.
+
+A subscriber is not required to have a bank account "soon".  Therefore,
+it can be created, and later be linked to one bank account.  For this
+reason, the ``$base`` should not mention one bank account.
+
+.. note::
+
+   Creating a subscriber is a time-consuming operation that goes often
+   through slow channels, therefore it should basically never be done
+   more than once.
+
+.. http:get:: $base/subscribers
+.. http:get:: $base/subscribers/$id
+.. http:post:: $base/subscribers
+.. http:post:: $base/subscribers/$id
+.. http:delete:: $base/subscribers/$id
+
+Transactions.
+^^^^^^^^^^^^^
+
+Transactions are money movements between bank accounts.
+
+For convenience, ``$base`` **could** mention one bank account
+to let customers see their transactions without defining "history"
+query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``.
+
+At the same time, transactions should be easy to query regardless
+of whose bank account they involve -- for administrative reasons, for
+example.  Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX``
+should be offered as well.
+
+.. http:get:: $base/transactions
+.. http:get:: $base/transactions/$id
+.. http:post:: $base/transactions
+.. http:post:: $base/transactions/$id
+.. http:delete:: $base/transactions/$id
+
+Customers.
+^^^^^^^^^^
+
+Customers are persons that **can** have one bank account.  As
+with subscribers, ``$base`` should not mention any bank account
+so as to leave more flexibility to assign new bank accounts to
+the same customer.
+
+.. http:get:: $base/customers
+.. http:get:: $base/customers/$id
+.. http:post:: $base/customers
+.. http:post:: $base/customers/$id
+.. http:delete:: $base/customers/$id
+
+Reports.
+^^^^^^^^
+
+Reports are persistent documents witnessing transactions.
+A typical example is a Camt.053 statement.  A report lives
+even after a bank account gets deleted or a customer leaves
+the bank, therefore ``$base`` should only mention a demobank
+instance.
+
+.. http:get:: $base/reports
+.. http:get:: $base/reports/$id
+.. http:post:: $base/reports
+.. http:post:: $base/reports/$id
+.. http:delete:: $base/reports/$id
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index f6ff682a..1f58a7db 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -2,95 +2,95 @@
 
 .. _sandbox-api:
 
-Current Sandbox API
-###################
+Sandbox API
+###########
 
-..
-  Current Sandbox endpoints.
+Demobanks.
+==========
 
-  GET /
-  Welcome message.
+Sandbox is designed to allow multiple *demobanks* being hosted,
+where every demobank can have its own configuration (including
+a different currency).  A demobank has a name, although currently
+only one demobank, named ``default``, is supported.  Such demobank
+activates the API segment ``/demobanks/default``, under which several
+APIs are then served.  The following sections describe all such APIs.
 
-  ** Camt debug **
+Access API.
+^^^^^^^^^^^
 
-  POST /admin/payments/camt
-  give last statement of requesting account
+Every endpoint is served under ``/demobanks/default/access-api``.
+See :doc:`/core/api-bank-access`.  This API offers *users management*.
 
-  ** Bank accounting **
+Integration API.
+^^^^^^^^^^^^^^^^
 
-  POST /admin/bank-accounts/$accountLabel
-  create bank account (no EBICS involved)
+Every endpoint is served under ``/demobanks/default/integration-api``.
+See :doc:`/core/api-bank-integration`.  This API handles the communication
+with Taler wallets.
 
-  GET /admin/bank-accounts
-  Give summary of all the bank accounts.
+Taler Wire Gateway API.
+^^^^^^^^^^^^^^^^^^^^^^^
 
-  GET /admin/bank-accounts/$accountLabel
-  give general information about a bank account
+Served under ``/demobanks/default/taler-wire-gateway``.  Currently,
+only the :ref:`admin/add-incoming <twg-admin-add-incoming>` endpoint
+is implemented.  This endpoint allows testing, but the rest of
+this API does never involve the Sandbox. 
 
-  ** Transactions **
-
-  POST /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
-  Book one incoming transaction for $accountLabel.
-  The debtor (not required to be in the same bank)
-  information is taken from the request.
-
-  GET /admin/bank-accounts/$accountLabel/transactions
-  Inform about all the transactions of one bank account.
-
-  POST /admin/bank-accounts/$accountLabel/generate-transactions
-  Generate one incoming and one outgoing transaction
-  for one bank account.
+EBICS API.
+^^^^^^^^^^
 
-  ** EBICS subscribers management **
+.. _demobank-create-ebics-subscriber:
 
-  POST /admin/ebics/subscribers
-  Create a new EBICS subscriber.
+.. http:post:: /demobanks/default/ebics/subscribers
 
-  GET /admin/ebics/subscribers
-  Give details of all the EBICS subscribers in the bank.
+   Allows (only) the *admin* user to associate a bank account
+   to a EBICS subscriber.  If the latter does not exist, it is
+   created.
 
-  POST /admin/ebics/bank-accounts
-  Create a *new* bank account and link it with an existing
-  EBICS subscriber.
+   **Request:**
 
-  ** EBICS host management **
+   .. ts:def:: SubscriberRequest
 
-  POST /admin/ebics/hosts/$hostID/rotate-keys
-  Change the bank's keys used in EBICS communication.
+     interface SubscriberRequest {
 
-  POST /admin/ebics/hosts
-  Create a new EBICS host.
+       // hostID
+       hostID: string;
 
-  GET /admin/ebics/hosts
-  Show details of all the EBICS hosts in the bank.
+       // userID
+       userID: string;
 
-  ** EBICS serving **
+       // partnerID
+       partnerID: string;
 
-  POST /ebicsweb
-  Processes a EBICS request.
+       // systemID, optional.
+       systemID: string;
 
-  ** Taler .. **
+       // Label of the bank account to associate with
+       // this subscriber.
+       demobankAccountLabel: string;
+     }
 
-  GET /taler
-  Show one taler://-URI to initiate a withdrawal.
+.. note::
 
-  - Taler integration API.
+  The following endpoints are **not** served under the ``/demobank/default`` segment.
 
-  - Demobank configuration API.
-    ToDo.
+Legacy API.
+===========
 
-  - Taler access API.
-    ToDo.
+This was the first API offered by Sandbox.  It is used in
+some test cases.  One is hosted at the Wallet repository; other
+MAY as well exist.
 
-EBICS.
-^^^^^^
+Except of the main EBICS handler located at "/ebicsweb", all
+the EBICS calls have to authenticate the 'admin' user via
+the HTTP basic auth scheme.
 
-Hosts.
-++++++
+EBICS Hosts.
+^^^^^^^^^^^^
 
 .. http:post:: /admin/ebics/hosts
 
-   Creates a new Ebics host.
+   Create a new EBICS host.
 
    **Request:**
 
@@ -128,9 +128,8 @@ Hosts.
    meant for tests (as the Sandbox itself is) and no backup will be
    produced along this operation.
 
-
-Subscribers.
-++++++++++++
+EBICS Subscribers.
+^^^^^^^^^^^^^^^^^^
 
 .. http:post:: /admin/ebics/bank-accounts
 
@@ -143,7 +142,11 @@ Subscribers.
      interface BankAccountRequest {
 
        // Ebics subscriber
-       subscriber: string;
+       subscriber: {
+         userID: string;
+         partnerID: string;
+         systemID: string;
+       };
 
        // IBAN
        iban: string;
@@ -157,39 +160,13 @@ Subscribers.
        // bank account label
        label: string;
 
-     }
-
-
-.. http:post:: /admin/ebics/subscribers
-
-   Creates a new Ebics subscriber.
-
-   **Request:**
-
-   .. ts:def:: SubscriberRequest
-
-     interface SubscriberRequest {
-
-       // hostID
-       hostID: string;
-
-       // userID
-       userID: string;
-
-       // partnerID
-       partnerID: string;
-
-       // systemID, optional.
-       systemID: string;
+       // Customer username that owns the bank account.
+       // Currency policy only allows same-named usernames
+       // and bank accounts.
+       owner: string;
 
-       // Label of the bank account to associate with
-       // this subscriber.  Note: the demobank name is
-       // omitted because every creation should happen
-       // under the /demobanks trunk.
-       demobankAccountLabel: string;
      }
 
-
 .. http:get:: /admin/ebics/subscribers
 
    Shows the list of all the subscribers in the system.
@@ -221,209 +198,213 @@ Subscribers.
         demobankAccountLabel: string;
       }
 
+.. http:post:: /admin/ebics/subscribers
+
+   Create a new EBICS subscriber without associating
+   a bank account to it.  This call is **deprecated**.
+   Follow `this page <https://bugs.gnunet.org/view.php?id=7507>`_
+   for updates over the EBICS management REST design.
+
+   .. ts:def:: SubscriberRequestDeprecated
+
+     interface SubscriberRequestDeprecated {
+
+       // hostID
+       hostID: string;
+
+       // userID
+       userID: string;
+
+       // partnerID
+       partnerID: string;
+
+       // systemID, optional.
+       systemID: string;
+
+     }
 
 Bank accounts.
 ^^^^^^^^^^^^^^
 
+The access to a particular bank account is granted either to the
+owner or to admin, via the HTTP basic auth scheme.  A 'owner' is
+a registered customer, who is identified by a username.  The
+registration of customers is offered via the :doc:`/core/api-bank-access`.
+
+.. note::
+
+   The current version allows only one bank account per
+   customer, where the bank account name (also called 'label')
+   equals the owner's username.
+
 .. http:get:: /admin/bank-accounts
 
-   Give summary of all the bank accounts.
+   Give summary of all the bank accounts.  Only admin allowed.
 
-.. http:get:: /admin/bank-accounts/$accountLabel
+   **Response:**
 
-   Give information about a bank account.
+   .. ts:def:: AdminBankAccount
 
-.. http:delete:: /demobanks/$demobankId/$accountLabel
+     interface AdminBankAccount {
 
-   Delete the bank account (and the customer entry) from the database.
-   Note, customer usernames and bank accounts have the same value.
+       // IBAN
+       iban: string;
 
-Main EBICS service.
-^^^^^^^^^^^^^^^^^^^
+       // BIC
+       bic: string;
 
-.. http:post:: /ebicsweb
+       // human name
+       name: string;
 
-   Serves all the Ebics requests.
+       // bank account label
+       label: string;
+     }
 
 
-Transactions.
-^^^^^^^^^^^^^
+.. http:get:: /admin/bank-accounts/$accountLabel
 
-JSON.
-+++++
+   Give information about a bank account.
 
-.. http:get:: /admin/bank-accounts/$accountLabel/transactions
+   **Response:**
 
-   Inform about all the transactions of one bank account.
+   .. ts:def:: AdminBankAccountBalance
 
-.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions
+     interface AdminBankAccountBalance {
+       // Balance in the $currency:$amount format.
+       balance: string; 
+       // IBAN of the bank account identified by $accountLabel
+       iban: string; 
+       // BIC of the bank account identified by $accountLabel
+       bic: string; 
+       // Mentions $accountLabel
+       label: string;
+     }
 
-   Generate one incoming and one outgoing transaction for one bank account.
+.. http:post:: /admin/bank-accounts/$accountLabel
 
-.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
+  Create bank account.  Existing users without a bank account
+  can request too.
 
-   Book one incoming transaction for $accountLabel.
-   The debtor (not required to be in the same bank)
-   information is taken from the request.
+  **Request:** :ts:type:`AdminBankAccount`
 
+Transactions.
+^^^^^^^^^^^^^
 
-Camt.
-+++++
+.. http:get:: /admin/bank-accounts/$accountLabel/transactions
 
-.. http:post:: /admin/payments/camt
+   Inform about all the transactions of one bank account.
 
-  Return the last statement of the requesting account.
+   **Response:**
 
-  **Request**
+   .. ts:def:: AdminTransactions
+   
+     interface AdminTransactions {
+       payments: AdminTransaction[]; 
+     }
 
-   .. code-block:: tsref
+   .. ts:def:: AdminTransaction
+   
+     interface AdminTransaction {
 
-     interface CamtParams {
+       // Label of the bank account involved in this payment.
+       accountLabel: string;
 
-       // label of the bank account being queried.
-       bankaccount: string;
+       // Creditor IBAN
+       creditorIban: string;
 
-       // The Camt type to return.  Only '53' is allowed
-       // at this moment.
-       type: number;
-     }
+       // Debtor IBAN
+       debtorIban: string;
 
-  **Response**
+       // UID given by one financial institute to this payment.
+       // FIXME: clarify whether that can be also assigned by
+       // the other party's institution. 
+       accountServicerReference: string;
 
-  The expected Camt.053 document.
+       // ID of the Pain.001 that initiated this payment.
+       paymentInformationId: string;
 
-Future Sandbox API
-##################
+       // Unstructured remittance information.
+       subject: string;
 
-Resources.
-^^^^^^^^^^
+       // Date of the payment in the HTTP header format.
+       date: string;
 
-Sandbox serves the following resources:
+       // The number amount as a string.
+       amount: string;
 
- - Demobanks.
- - Bank accounts.
- - Subscribers.
- - Transactions.
- - Customers.
- - Reports.
+       // BIC of the creditor IBAN.
+       creditorBic: string;
 
-The resources are subject to all CRUD operations, via by two
-types of users: the 'admin' and the customers.  The admin has
-rights on all of them.
+       // Legal name of the creditor.
+       creditorName: string;
 
-One of the main differences with the previous versions is the
-removal of the "/admin" initial component.  If the administrator
-authenticates for one operation, then this one is of type ``admin``:
-no need for a dedicated and extra URI path component.
+       // BIC of the debtor IBAN.
+       debtorBic: string;
 
-For example, mocking transactions in the system was a typical
-/admin-operation, but since transactions themselves are resources
-and any resource is subject to CRUD operations, then mocking one
-becomes just a ``C`` operation on the 'transactions' resources.  If
-a test case wants to simplify the authentication - by hard-coding
-the credentials, for example - before mocking one transaction, then
-it can impersonate the administrator.
+       // Legal name of the debtor.
+       debtorName: string;
 
-.. note::
+       // Payment's currency
+       currency: string;
 
-   ``POST``\ ing to an endpoint with a trailing ``$id`` means
-   modification of an existing resource.
+       // Have values 'credit' or 'debit' relative
+       // to the requesting user.
+       creditDebitIndicator: string;
+     }
 
-Demobanks
-^^^^^^^^^
+.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions
 
-Demobanks are the main containers of all the other resources.
-They take configuration values, like the currency for example.
+   Generate one incoming and one outgoing transaction for the bank account
+   identified by ``$accountLabel``.  Only admin allowed.
 
-.. http:get:: /admin/demobanks
-.. http:get:: /admin/demobanks/$id
-.. http:post:: /admin/demobanks
-.. http:post:: /admin/demobanks/$id
-.. http:delete:: /admin/demobanks/$id
+.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
 
-Bank accounts.
-^^^^^^^^^^^^^^
+   Book one incoming transaction for $accountLabel.
+   The debtor (not required to be in the same bank)
+   information is taken from the request.  Only admin allowed.
 
-Bank accounts collect money of customers and participate
-in transactions.
+   **Request:**
+   
+   .. ts:def:: AdminSimulateTransaction
 
-The ``$base`` is one demobank, in the form ``/demobanks/$id``.
-That is due because a bank account must inherit some defaults
-from the demobank, like the currency.
+     interface AdminSimulateTransaction {
 
-.. http:get:: $base/bankaccounts
-.. http:get:: $base/bankaccounts/$id
-.. http:post:: $base/bankaccounts
-.. http:post:: $base/bankaccounts/$id
-.. http:delete:: $base/bankaccounts/$id
+       // Debtor IBAN.
+       debtorIban: string; 
 
-Subscribers.
-^^^^^^^^^^^^
+       // Debtor BIC.
+       debtorBic: string; 
 
-Subscribers are (optional) customers identities for protocols
-other than the native one.
+       // Debtor name.
+       debtorName: string; 
 
-A subscriber is not required to have a bank account "soon".  Therefore,
-it can be created, and later be linked to one bank account.  For this
-reason, the ``$base`` should not mention one bank account.
+       // Amount number (without currency) as a string.
+       amount: string;
 
-.. note::
+       // Payment subject.
+       subject: string;
+     }
 
-   Creating a subscriber is a time-consuming operation that goes often
-   through slow channels, therefore it should basically never be done
-   more than once.
 
-.. http:get:: $base/subscribers
-.. http:get:: $base/subscribers/$id
-.. http:post:: $base/subscribers
-.. http:post:: $base/subscribers/$id
-.. http:delete:: $base/subscribers/$id
+.. http:post:: /admin/payments/camt
 
-Transactions.
-^^^^^^^^^^^^^
+  Return the last camt.053 document from the requesting account.
 
-Transactions are money movements between bank accounts.
+  **Request**
 
-For convenience, ``$base`` **could** mention one bank account
-to let customers see their transactions without defining "history"
-query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``.
+   .. code-block:: tsref
 
-At the same time, transactions should be easy to query regardless
-of whose bank account they involve -- for administrative reasons, for
-example.  Hence, a "global" URI scheme like ``$demobank/transactions?param=XXX``
-should be offered as well.
+     interface CamtParams {
 
-.. http:get:: $base/transactions
-.. http:get:: $base/transactions/$id
-.. http:post:: $base/transactions
-.. http:post:: $base/transactions/$id
-.. http:delete:: $base/transactions/$id
+       // label of the bank account being queried.
+       bankaccount: string;
 
-Customers.
-^^^^^^^^^^
+       // The Camt type to return.  Only '53' is allowed
+       // at this moment.
+       type: number;
+     }
+
+  **Response**
 
-Customers are persons that **can** have one bank account.  As
-with subscribers, ``$base`` should not mention any bank account
-so as to leave more flexibility to assign new bank accounts to
-the same customer.
-
-.. http:get:: $base/customers
-.. http:get:: $base/customers/$id
-.. http:post:: $base/customers
-.. http:post:: $base/customers/$id
-.. http:delete:: $base/customers/$id
-
-Reports.
-^^^^^^^^
-
-Reports are persistent documents witnessing transactions.
-A typical example is a Camt.053 statement.  A report lives
-even after a bank account gets deleted or a customer leaves
-the bank, therefore ``$base`` should only mention a demobank
-instance.
-
-.. http:get:: $base/reports
-.. http:get:: $base/reports/$id
-.. http:post:: $base/reports
-.. http:post:: $base/reports/$id
-.. http:delete:: $base/reports/$id
+  The last Camt.053 document related to the bank account
+  mentioned in the request body.