[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] branch master updated: Sandbox API.
From: |
gnunet |
Subject: |
[taler-docs] branch master updated: Sandbox API. |
Date: |
Thu, 01 Dec 2022 17:09:36 +0100 |
This is an automated email from the git hooks/post-receive script.
ms pushed a commit to branch master
in repository docs.
The following commit(s) were added to refs/heads/master by this push:
new 0d921da Sandbox API.
0d921da is described below
commit 0d921da53e2532bed1de11b5855a684e9ecf4754
Author: MS <ms@taler.net>
AuthorDate: Thu Dec 1 17:06:54 2022 +0100
Sandbox API.
Match endpoints with implementation.
---
core/api-bank-access.rst | 21 +--
core/api-wire.rst | 2 +
libeufin/api-sandbox-future.rst | 135 +++++++++++++++++++
libeufin/api-sandbox.rst | 289 ++++++++++------------------------------
4 files changed, 217 insertions(+), 230 deletions(-)
diff --git a/core/api-bank-access.rst b/core/api-bank-access.rst
index a33cbdb..8257839 100644
--- a/core/api-bank-access.rst
+++ b/core/api-bank-access.rst
@@ -81,7 +81,7 @@ name and account password, at least in the GNU Taler demo
bank implementation.
}
-.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
+.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals
Create a withdrawal operation, resulting in a ``taler://withdraw`` URI.
@@ -107,7 +107,7 @@ name and account password, at least in the GNU Taler demo
bank implementation.
}
-.. http:GET::
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}
+.. http:get::
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}
Query the status of a withdrawal operation.
@@ -143,7 +143,7 @@ name and account password, at least in the GNU Taler demo
bank implementation.
}
-.. http:POST::
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort
+.. http:post::
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/abort
Abort a withdrawal operation. Has no effect on an already aborted
withdrawal operation.
@@ -151,7 +151,7 @@ name and account password, at least in the GNU Taler demo
bank implementation.
:http:statuscode:`409 Conflict`: The reserve operation has been confirmed
previously and can't be aborted.
-.. http:POST::
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm
+.. http:post::
${BANK_API_BASE_URL}/accounts/${account_name}/withdrawals/${withdrawal_id}/confirm
Confirm a withdrawal operation. Has no effect on an already confirmed
withdrawal operation.
This call is responsible of wiring the funds to the exchange.
@@ -169,7 +169,7 @@ name and account password, at least in the GNU Taler demo
bank implementation.
Transactions
------------
-.. http:GET:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
+.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
Retrieve a subset of transactions related to $account_name. Without
query parameters, it returns the last 5 transactions.
@@ -187,7 +187,7 @@ Transactions
transactions: BankAccountTransactionInfo[];
}
-.. http:GET::
${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}
+.. http:get::
${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}
**Response**
@@ -218,7 +218,7 @@ Transactions
}
-.. http:POST:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
+.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
Create a new transaction where the bank account with the label
``account_name`` is **debited**.
@@ -247,11 +247,16 @@ Transactions
:http:statuscode:`400 Bad Request`:
the request was invalid or the payto://-URI used unacceptable features.
+.. http:delete:: ${BANK_API_BASE_URL}/accounts/${account_name}
+
+ Delete the bank account (and the customer entry) from the database.
+ Note, customer usernames and bank accounts have the same value.
+
----------------------
Registration (Testing)
----------------------
-.. http:POST:: ${BANK_API_BASE_URL}/testing/register
+.. http:post:: ${BANK_API_BASE_URL}/testing/register
Create a new bank account. This endpoint should be disabled for most
deployments, but is useful
for automated testing / integration tests.
diff --git a/core/api-wire.rst b/core/api-wire.rst
index 63373f6..34c0a0f 100644
--- a/core/api-wire.rst
+++ b/core/api-wire.rst
@@ -327,6 +327,8 @@ Wire Transfer Test APIs
Endpoints in this section are only used for integration tests and never
exposed by bank gateways in production.
+.. _twg-admin-add-incoming:
+
.. http:post:: ${BASE_URL}/admin/add-incoming
Simulate a transfer from a customer to the exchange. This API is *not*
diff --git a/libeufin/api-sandbox-future.rst b/libeufin/api-sandbox-future.rst
new file mode 100644
index 0000000..06dfc68
--- /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 f6ff682..8201b80 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 <demobank-create-ebics-subscriber>`.
- 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 <twg-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 <https://bugs.gnunet.org/view.php?id=7507>`_
+ 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.
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.
- [taler-docs] branch master updated: Sandbox API.,
gnunet <=