diff options
Diffstat (limited to 'libeufin/api-sandbox.rst')
| -rw-r--r-- | libeufin/api-sandbox.rst | 417 |
1 files changed, 0 insertions, 417 deletions
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst deleted file mode 100644 index b75fcf8d..00000000 --- a/libeufin/api-sandbox.rst +++ /dev/null @@ -1,417 +0,0 @@ -.. target audience: developer, core developer - -.. _sandbox-api: - -Current Sandbox API -################### - -.. - Current Sandbox endpoints. - - GET / - Welcome message. - - ** 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 a existing - EBICS subscriber. - - ** EBICS host management ** - - POST /admin/ebics/hosts/$hostID/rotate-keys - Change the bank's keys used in EBICS communication. - - POST /admin/ebics/hosts - Create a new EBICS host. - - GET /admin/ebics/hosts - Show details of all the EBICS hosts in the bank. - - ** EBICS serving ** - - POST /ebicsweb - Processes a EBICS request. - - ** Taler .. ** - - GET /taler - Show one taler://-URI to initiate a withdrawal. - - - Taler integration API. - - - Demobank configuration API. - ToDo. - - - Taler access API. - ToDo. - -EBICS. -^^^^^^ - -Hosts. -++++++ - -.. http:post:: /admin/ebics/hosts - - Creates a new Ebics host. - - **Request:** - - .. ts:def:: EbicsHostRequest - - interface EbicsHostRequest { - - // Ebics version. - hostID: string; - - // Name of the host. - ebicsVersion: string; - } - - -.. http:get:: /admin/ebics/hosts - - Shows the list of all the hosts in the system. - - **Response:** - - .. ts:def:: EbicsHostResponse - - interface EbicsHostResponse { - - // shows the host IDs that are active in the system. - // The Ebics version *is* missing, but it's still available - // via the HEV message. - ebicsHosts: string[]; - } - -.. http:post:: /admin/ebics/hosts/$hostID/rotate-keys - - Overwrite the bank's Ebics keys with random ones. This is entirely - meant for tests (as the Sandbox itself is) and no backup will be - produced along this operation. - - -Subscribers. -++++++++++++ - -.. http:post:: /admin/ebics/bank-accounts - - Associates a new bank account to an existing subscriber. - - **Request:** - - .. ts:def:: BankAccountRequest - - interface BankAccountRequest { - - // Ebics subscriber - subscriber: string; - - // IBAN - iban: string; - - // BIC - bic: string; - - // human name - name: string; - - // bank account label - label: string; - - } - - -.. http:post:: /admin/ebics/subscribers - - Creates a new Ebics subscriber. - - **Request:** - - .. ts:def:: SubscriberRequest - - interface SubscriberRequest { - - // hostID - hostID: string; - - // userID - userID: string; - - // partnerID - partnerID: string; - - // systemID - systemID: string; - - } - - -.. http:get:: /admin/ebics/subscribers - - Shows the list of all the subscribers in the system. - - **Response:** - - .. ts:def:: SubscribersResponse - - interface SubscribersResponse { - - subscribers: Subscriber[] - } - - .. ts:def:: Subscriber - - interface Subscriber { - - // userID - userID: string; - - // partnerID - partnerID: string; - - // hostID - hostID: string; - - } - - -Bank accounts. -^^^^^^^^^^^^^^ - -.. http:get:: /admin/bank-accounts - - Give summary of all the bank accounts. - -.. http:get:: /admin/bank-accounts/$accountLabel - - Give information about a bank account. - - -Main EBICS service. -^^^^^^^^^^^^^^^^^^^ - -.. http:post:: /ebicsweb - - Serves all the Ebics requests. - - -Transactions. -^^^^^^^^^^^^^ - -JSON. -+++++ - -.. http:get:: /admin/bank-accounts/$accountLabel/transactions - - Inform about all the transactions of one bank account. - -.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions - - Generate one incoming and one outgoing transaction for one bank account. - -.. http: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. - - -Camt. -+++++ - -.. http:post:: /admin/payments/camt - - Return the last statement of the requesting account. - - **Request** - - .. code-block:: tsref - - interface CamtParams { - - // label of the bank account being queried. - bankaccount: string; - - // The Camt type to return. Only '53' is allowed - // at this moment. - type: number; - } - - **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 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 - modification of a 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 |