diff options
Diffstat (limited to 'libeufin/api-sandbox-future.rst')
| -rw-r--r-- | libeufin/api-sandbox-future.rst | 135 |
1 files changed, 135 insertions, 0 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 |