summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorms <ms@taler.net>2021-10-14 09:58:44 +0200
committerms <ms@taler.net>2021-10-14 09:58:44 +0200
commit086c56955edcd83c41b6983bc071d67cd88c9fc8 (patch)
tree64394bf7eb0560e1e88fe237dee281eed1167f7d
parent9f838cc4c19c3e9c815757d8616393d9dd3b457f (diff)
downloaddocs-086c56955edcd83c41b6983bc071d67cd88c9fc8.tar.gz
docs-086c56955edcd83c41b6983bc071d67cd88c9fc8.tar.bz2
docs-086c56955edcd83c41b6983bc071d67cd88c9fc8.zip
Sandbox API.
Elaborating on the resources.
-rw-r--r--libeufin/api-sandbox.rst100
1 files changed, 67 insertions, 33 deletions
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 2d385df..b75fcf8 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