Sandbox API.

Elaborating on the resources.

1 files changed, 67 insertions, 33 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 2d385df4..b75fcf8d 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -2,30 +2,6 @@
 
 .. _sandbox-api:
 
-Resources.
-##########
-
-Sandbox serves the following resources:
-
- - Demobanks.
- - Bank accounts.
- - Subscribers.
- - Transactions.
- - Customers.
- - Reports.
- 
-Such resources are subject to all CRUD operations through
-two main trunks: ``/admin`` and ``/demobanks``.
-
-the admin trunk has total rights on all of them, whereas the
-``/demobank`` can only reach as far as a bank customer is allowed
-to.  For example, under the admin trunk will be possible to create
-and/or delete a new demobank (with its own configuration values),
-but that'll be forbidden under the demobank trunk.
-
-Hence typically, the admin trunk has all the accesses protected
-by a access token.
-
 Current Sandbox API
 ###################
 
@@ -35,6 +11,8 @@ Current Sandbox API
   GET /
   Welcome message.
 
+  ** Camt debug **
+
   POST /admin/payments/camt 
   give last statement of requesting account
 
@@ -49,6 +27,8 @@ Current Sandbox API
   GET /admin/bank-accounts/$accountLabel 
   give general information about a bank account
 
+  ** 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)
@@ -95,7 +75,6 @@ Current Sandbox API
   Show one taler://-URI to initiate a withdrawal.
 
   - Taler integration API.
-    80% done.
 
   - Demobank configuration API.
     ToDo.
@@ -304,6 +283,35 @@ Camt.
 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 dedicate and extra URI part.
+
+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 a endpoint with a trailing ``$id`` means
@@ -312,7 +320,8 @@ Future Sandbox API
 Demobanks
 ^^^^^^^^^
 
-Demobanks contain bank accounts, and are configurable.
+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
@@ -323,9 +332,13 @@ Demobanks contain bank accounts, and are configurable.
 Bank accounts.
 ^^^^^^^^^^^^^^
 
-Bank accounts collect money of users and participate
+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
@@ -338,6 +351,16 @@ 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
@@ -349,20 +372,28 @@ 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
 
-.. note::
-   A "history" endpoint can be implemented by providing
-   some filtering parameters to the first GET call.
-
 Customers.
 ^^^^^^^^^^
 
-Customers are persons with at least one bank account.
+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
@@ -374,7 +405,10 @@ Reports.
 ^^^^^^^^
 
 Reports are persistent documents witnessing transactions.
-A typical example is a Camt.053 report.
+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