From 086c56955edcd83c41b6983bc071d67cd88c9fc8 Mon Sep 17 00:00:00 2001 From: ms Date: Thu, 14 Oct 2021 09:58:44 +0200 Subject: Sandbox API. Elaborating on the resources. --- libeufin/api-sandbox.rst | 100 +++++++++++++++++++++++++++++++---------------- 1 file 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 -- cgit v1.2.3