diff options
Diffstat (limited to 'libeufin/api-sandbox.rst')
| -rw-r--r-- | libeufin/api-sandbox.rst | 365 |
1 files changed, 275 insertions, 90 deletions
diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst index b30061ae..b75fcf8d 100644 --- a/libeufin/api-sandbox.rst +++ b/libeufin/api-sandbox.rst @@ -2,104 +2,91 @@ .. _sandbox-api: -Sandbox API -########### +Current Sandbox API +################### .. Current Sandbox endpoints. - POST /register - GET /jinja-test - GET /profile - GET /static GET / - GET /config - POST /admin/payments/camt - POST /admin/bank-accounts/$accountLabel - GET /admin/bank-accounts/$accountLabel - POST /admin/bank-accounts/$accountLabel/simulate-incoming-transaction - POST /admin/payments - POST /admin/ebics/bank-accounts - GET /admin/bank-accounts - GET /admin/bank-accounts/$accountLabel/transactions - POST /admin/bank-accounts/$accountLabel/generate-transactions - POST /admin/ebics/subscribers - GET /admin/ebics/subscribers - POST /admin/ebics/hosts/$hostID/rotate-keys - POST /admin/ebics/hosts - GET /admin/ebics/hosts - POST /ebicsweb + Welcome message. -HTTP API -======== + ** Camt debug ** -.. - Payments. + POST /admin/payments/camt + give last statement of requesting account + ** Bank accounting ** -.. http:post:: /admin/payments/camt + POST /admin/bank-accounts/$accountLabel + create bank account (no EBICS involved) - Return the history of one IBAN in Camt.053 format. + GET /admin/bank-accounts + Give summary of all the bank accounts. - **Request** + GET /admin/bank-accounts/$accountLabel + give general information about a bank account - .. code-block:: tsref + ** Transactions ** - interface CamtParams { + 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. - // label of the bank account being queried. - bankaccount: string; + GET /admin/bank-accounts/$accountLabel/transactions + Inform about all the transactions of one bank account. - // The Camt type to return. Only '53' is allowed - // at this moment. - type: number; - } + POST /admin/bank-accounts/$accountLabel/generate-transactions + Generate one incoming and one outgoing transaction + for one bank account. - **Response** + ** EBICS subscribers management ** - The expected Camt.053 document. + POST /admin/ebics/subscribers + Create a new EBICS subscriber. + + GET /admin/ebics/subscribers + Give details of all the EBICS subscribers in the bank. -.. http:post:: /admin/payments + POST /admin/ebics/bank-accounts + Create a *new* bank account and link it with a existing + EBICS subscriber. - Adds a new payment to the book. Mainly used for testing - purposes. + ** EBICS host management ** - **Request:** + POST /admin/ebics/hosts/$hostID/rotate-keys + Change the bank's keys used in EBICS communication. - One object of type `SandboxPayment` + POST /admin/ebics/hosts + Create a new EBICS host. - .. ts:def:: SandboxPayment + GET /admin/ebics/hosts + Show details of all the EBICS hosts in the bank. - interface SandboxPayment { + ** EBICS serving ** - // IBAN that will receive the payment. - creditorIban: string; - // FIXME - creditorBic: string; - // FIXME - creditorName: string; + POST /ebicsweb + Processes a EBICS request. - // IBAN that will send the payment. - debitorIban: string; - // FIXME - debitorBic: string; - // FIXME - debitorName: string; + ** Taler .. ** - amount: string; - currency: string; + GET /taler + Show one taler://-URI to initiate a withdrawal. - // subject of the payment. - subject: string; + - Taler integration API. - // Whether the payment is credit or debit *for* the - // account being managed *by* the running sandbox. - // Can take the values: "CRDT" or "DBIT". - direction: string; - } + - Demobank configuration API. + ToDo. -.. - Host management. + - Taler access API. + ToDo. + +EBICS. +^^^^^^ + +Hosts. +++++++ .. http:post:: /admin/ebics/hosts @@ -141,8 +128,37 @@ HTTP API meant for tests (as the Sandbox itself is) and no backup will be produced along this operation. -.. - Subscriber management. + +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 @@ -197,36 +213,205 @@ HTTP API } -.. http:post:: /admin/ebics/bank-accounts - Associates a new bank account to an existing subscriber. +Bank accounts. +^^^^^^^^^^^^^^ - **Request:** +.. http:get:: /admin/bank-accounts - .. ts:def:: BankAccountRequest + Give summary of all the bank accounts. - interface BankAccountRequest { +.. http:get:: /admin/bank-accounts/$accountLabel - // Ebics subscriber - subscriber: string; + Give information about a bank account. - // IBAN - iban: string; - // BIC - bic: string; +Main EBICS service. +^^^^^^^^^^^^^^^^^^^ - // human name - name: string; +.. http:post:: /ebicsweb - // bank account label - label: string; + 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; } -.. - Main EBICS service. + **Response** -.. http:post:: /ebicsweb + The expected Camt.053 document. - Serves all the Ebics requests. +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 |