From 0d921da53e2532bed1de11b5855a684e9ecf4754 Mon Sep 17 00:00:00 2001 From: MS Date: Thu, 1 Dec 2022 17:06:54 +0100 Subject: Sandbox API. Match endpoints with implementation. --- libeufin/api-sandbox-future.rst | 135 +++++++++++++++++++ libeufin/api-sandbox.rst | 289 ++++++++++------------------------------ 2 files changed, 202 insertions(+), 222 deletions(-) create mode 100644 libeufin/api-sandbox-future.rst (limited to 'libeufin') 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..8201b807 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -2,88 +2,54 @@ .. _sandbox-api: -Current Sandbox API -################### +.. http:get:: / -.. - Current Sandbox endpoints. + Greeting page. - GET / - Welcome message. +Sandbox API +########### - ** Camt debug ** - - POST /admin/payments/camt - give last statement of requesting account - - ** Bank accounting ** - - POST /admin/bank-accounts/$accountLabel - create bank account (no EBICS involved) - - GET /admin/bank-accounts - Give summary of all the bank accounts. - - 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) - 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 subscribers management ** - - POST /admin/ebics/subscribers - Create a new EBICS subscriber. - - GET /admin/ebics/subscribers - Give details of all the EBICS subscribers in the bank. - - POST /admin/ebics/bank-accounts - Create a *new* bank account and link it with an existing - EBICS subscriber. - - ** EBICS host management ** +Demobanks. +^^^^^^^^^^ - POST /admin/ebics/hosts/$hostID/rotate-keys - Change the bank's keys used in EBICS communication. +Sandbox is designed to allow multiple banks 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 trunk ``/demobanks/default``, under which other +APIs are then served. Those APIs include Access API, Integration +API, (part of the) Wire Gateway API (the add-incoming call), and +:ref:`one call to create EBICS subscribers `. - POST /admin/ebics/hosts - Create a new EBICS host. +Access API. +^^^^^^^^^^ - GET /admin/ebics/hosts - Show details of all the EBICS hosts in the bank. +Every endpoint is served under ``/demobanks/default/access-api``. +See :doc:`/core/api-bank-access`. - ** EBICS serving ** +Integration API. +^^^^^^^^^^^^^^^^ - POST /ebicsweb - Processes a EBICS request. +Every endpoint is served under ``/demobanks/default/integration-api``. +See :doc:`/core/api-bank-integration`. - ** Taler .. ** +Taler Wire Gateway API. +^^^^^^^^^^^^^^^^^^^^^^^ - GET /taler - Show one taler://-URI to initiate a withdrawal. +Served under ``/demobanks/default/taler-wire-gateway``. Currently, +only the :ref:`admin/add-incoming ` endpoint +is implemented. This endpoint allows testing, whereas the rest of +this API does never involve the Sandbox. - - Taler integration API. +EBICS. +^^^^^^ - - Demobank configuration API. - ToDo. +HTTP Service +++++++++++++ - - Taler access API. - ToDo. +.. http:post:: /ebicsweb -EBICS. -^^^^^^ + Serves all the Ebics requests. Hosts. ++++++ @@ -159,10 +125,12 @@ Subscribers. } +.. _demobank-create-ebics-subscriber: -.. http:post:: /admin/ebics/subscribers +.. http:post:: /demobanks/default/ebics/subscribers - Creates a new Ebics subscriber. + Creates a new Ebics subscriber without associating + a bank account to it. **Request:** @@ -183,13 +151,10 @@ Subscribers. systemID: 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. + // this subscriber. demobankAccountLabel: string; } - .. http:get:: /admin/ebics/subscribers Shows the list of all the subscribers in the system. @@ -221,6 +186,30 @@ 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 `_ + 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. ^^^^^^^^^^^^^^ @@ -233,18 +222,9 @@ Bank accounts. Give information about a bank account. -.. http:delete:: /demobanks/$demobankId/$accountLabel - - Delete the bank account (and the customer entry) from the database. - Note, customer usernames and bank accounts have the same value. - -Main EBICS service. -^^^^^^^^^^^^^^^^^^^ - -.. http:post:: /ebicsweb - - Serves all the Ebics requests. +.. http:post:: /admin/bank-accounts/$accountLabel + create bank account. Transactions. ^^^^^^^^^^^^^ @@ -290,140 +270,5 @@ Camt. **Response** - The expected Camt.053 document. - -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 + The last Camt.053 document related to the bank account + mentioned in the request body. -- cgit v1.2.3