commit 3036b21e51fb494886acf903e135d2115340bd35
parent 6567bd869fd123989553211fd09b3b5702fa0948
Author: Christian Grothoff <christian@grothoff.org>
Date: Tue, 6 Dec 2022 13:02:31 +0100
Merge branch 'master' of git+ssh://git.taler.net/docs
Diffstat:
9 files changed, 811 insertions(+), 309 deletions(-)
diff --git 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-merchant.rst b/core/api-merchant.rst
@@ -16,6 +16,7 @@
@author Marcello Stanisci
@author Florian Dold
@author Christian Grothoff
+ @author Priscilla Huang
.. _merchant-api:
@@ -2972,7 +2973,7 @@ Checking tip status
Template
--------
-The templates is a backend feature that is used to create an order. We use the template to have some static information that cannot be changed by the customer.
+The template is a backend feature that is used to create an order. We use the template to have some static information that cannot be changed by the customer.
The template is private and allows us to be flexible. The private template allows for greater security and allows us to have a minimum information we need for each store.
@@ -2982,19 +2983,19 @@ Adding templates
.. http:post:: [/instances/$INSTANCE]/private/templates
- This is used to create a template.
+ This is used to create a template.
- **Request:**
+ **Request:**
- The request must be a `TemplateAddDetails`.
+ The request must be a `TemplateAddDetails`.
- **Response:**
+ **Response:**
- :http:statuscode:`204 No content`:
- The creation of the template is successful.
- :http:statuscode:`404 Not found`:
- The merchant instance is unknown or it is not in our data.
+ :http:statuscode:`204 No content`:
+ The creation of the template is successful.
+ :http:statuscode:`404 Not found`:
+ The merchant instance is unknown or it is not in our data.
.. ts:def:: TemplateAddDetails
@@ -3045,21 +3046,21 @@ Editing templates
.. http:patch:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID
- This is used to update a template.
+ This is used to update a template.
- **Request:**
+ **Request:**
- The request must be a `TemplatePatchDetails`.
+ The request must be a `TemplatePatchDetails`.
- **Response:**
+ **Response:**
- :http:statuscode:`204 No content`:
- The templates has successfully modified.
- :http:statuscode:`404 Not found`:
- The templates(ID) is unknown to the backend.
- :http:statuscode:`409 Conflict`:
- The provided information is inconsistent with the current state of the template. Changes made is the same with
- another store.
+ :http:statuscode:`204 No content`:
+ The template has successfully modified.
+ :http:statuscode:`404 Not found`:
+ The template(ID) is unknown to the backend.
+ :http:statuscode:`409 Conflict`:
+ The provided information is inconsistent with the current state of the template. Changes made is the same with
+ another store.
.. ts:def:: TemplatePatchDetails
@@ -3086,14 +3087,14 @@ Inspecting template
.. http:get:: [/instances/$INSTANCE]/private/templates
- This is used to return the list of all the templates.
+ This is used to return the list of all the templates.
- **Response:**
+ **Response:**
- :http:statuscode:`200 OK`:
+ :http:statuscode:`200 OK`:
The backend has successfully returned all the templates. Returns a `TemplateSummaryResponse`.
- :http:statuscode:`404 Not found`:
+ :http:statuscode:`404 Not found`:
The backend has does not know about the instance.
@@ -3107,7 +3108,7 @@ Inspecting template
-The `TemplatesEntry` object describes a template. It has the following structure:
+ The `TemplatesEntry` object describes a template. It has the following structure:
@@ -3127,16 +3128,16 @@ The `TemplatesEntry` object describes a template. It has the following structure
.. http:get:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID
- This is used to obtain detailed information about a specific template.
+ This is used to obtain detailed information about a specific template.
- **Response:**
+ **Response:**
- :http:statuscode:`200 OK`:
- The backend has successfully returned the detailed information about a specific template.
- Returns a `TemplateDetails`.
- :http:statuscode:`404 Not found`:
- The template(ID) is unknown to the backend.
+ :http:statuscode:`200 OK`:
+ The backend has successfully returned the detailed information about a specific template.
+ Returns a `TemplateDetails`.
+ :http:statuscode:`404 Not found`:
+ The template(ID) is unknown to the backend.
.. ts:def:: TemplateDetails
@@ -3162,14 +3163,14 @@ Removing template
.. http:delete:: [/instances/$INSTANCE]/private/templates/$TEMPLATE_ID
- This is used to delete information about a template.
+ This is used to delete information about a template.
- **Response:**
+ **Response:**
- :http:statuscode:`204 No content`:
- The backend has successfully deleted the template.
- :http:statuscode:`404 Not found`:
- The backend does not know the instance or the template.
+ :http:statuscode:`204 No content`:
+ The backend has successfully deleted the template.
+ :http:statuscode:`404 Not found`:
+ The backend does not know the instance or the template.
@@ -3178,25 +3179,25 @@ Using template
.. http:post:: [/instances/$INSTANCES]/templates/$TEMPLATE_ID
- This using template can be modified by everyone and will be used to create order.
+ This using template can be modified by everyone and will be used to create order.
- **Request:**
+ **Request:**
- The request must be a `UsingTemplateDetails` and we accept JSON application and URL encoded.
+ The request must be a `UsingTemplateDetails` and we accept JSON application and URL encoded.
- **Response:**
+ **Response:**
- :http:statuscode:`200 OK`:
- The using template is successful. Returns a `UsingTemplateResponse`.
- :http:statuscode:`302 Found`:
- The client should go to the indicated location. Only returned if the content type was HTML. The target site may allow the client to pay his order.
- :http:statuscode:`404 Not found`:
- The merchant instance is unknown or the template is unknown.
+ :http:statuscode:`200 OK`:
+ The using template is successful. Returns a `UsingTemplateResponse`.
+ :http:statuscode:`302 Found`:
+ The client should go to the indicated location. Only returned if the content type was HTML. The target site may allow the client to pay his order.
+ :http:statuscode:`404 Not found`:
+ The merchant instance is unknown or the template is unknown.
- .. ts:def:: UsingTemplateDetails
+ .. ts:def:: UsingTemplateDetails
interface UsingTemplateDetails {
@@ -3205,19 +3206,210 @@ Using template
// The amount entered by the customer.
amount?: Amount;
- }
+ }
- .. ts:def:: UsingTemplateResponse
+ .. ts:def:: UsingTemplateResponse
interface UsingTemplateResponse {
// After enter the request. The user will be pay with a taler URL.
taler_url: string;
-
}
+
+
+
+
+
+--------
+Webhooks
+--------
+
+The webhook is a backend feature that is used to send a confirmation to the merchant. It can be send with a SMS, email or with another method. It will confirm that the
+customer paid the merchant. It will show the date and the price the customer paid.
+
+
+
+Adding webhooks
+---------------
+
+.. http:post:: [/instances/$INSTANCES]/private/webhooks
+
+ This is used to create a webhook.
+
+ **Request:**
+
+ The request must be a `WebhookAddDetails`.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The creation of the webhook is successsful.
+
+ :http:statuscode:`404 Not found`:
+ The merchant instance is unknowm or it not in our data.
+
+ .. ts:def:: WebhookAddDetails
+
+ interface WebhookAddDetails {
+
+ // Webhook ID to use.
+ webhook_id: string;
+
+ // The event of the webhook: why the webhook is used.
+ event_type: string;
+
+ // URL of the webhook where the customer will be redirected.
+ url: string;
+
+ // Method used by the webhook
+ http_method: string;
+
+ // Header template of the webhook
+ header_template?: string;
+
+ // Body template by the webhook
+ body_template?: string;
+
+ }
+
+
+Editing webhooks
+----------------
+
+.. http:patch:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
+
+ This is used to update a webhook.
+
+ **Request:**
+
+ The request must be a `WebhookPatchDetails`.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The webhook has successfully modified.
+ :http:statuscode:`404 Not found`:
+ The webhook(ID) is unknown to the backend.
+ :http:statuscode:`409 Conflict`:
+ The provided information is inconsistent with the current state of the webhook. Changes made is the same with another store.
+
+ .. ts:def:: WebhookPatchDetails
+
+ interface WebhookPatchDetails {
+
+ // The event of the webhook: why the webhook is used.
+ event_type: string;
+
+ // URL of the webhook where the customer will be redirected.
+ url: string;
+
+ // Method used by the webhook
+ http_method: string;
+
+ // Header template of the webhook
+ header_template?: string;
+
+ // Body template by the webhook
+ body_template?: string;
+
+ }
+
+
+
+Inspecting webhook
+------------------
+
+.. http:get:: [/instances/$INSTANCES]/private/webhooks
+
+ This is used to return the list of all the webhooks.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The backend has successfully returned all the webhooks. Returns a `WebhookSummaryResponse`.
+
+ :http:statuscode:`404 Not found`:
+ The backend has does not know about the instance.
+
+ .. ts:def:: WebhookSummaryResponse
+
+ interface WebhookSummaryResponse {
+
+ // List of webhooks that are present in our backend.
+ webhooks_list: WebhookEntry[];
+
+ }
+
+ The WebhookEntry object describes a webhook. It has the following structure:
+
+ .. ts:def:: WebhookEntry
+
+ interface WebhookEntry {
+
+ // Webhook identifier, as found in the webhook.
+ webhook_id: string;
+
+ // The event of the webhook: why the webhook is used.
+ event_type: string;
+
+ }
+
+
+.. http:get:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
+
+ This is used to obtain detailed information about apecific template.
+
+ **Response:**
+
+ :http:statuscode:`200 OK`:
+ The backend has successfully returned the detailed information about a specific webhook. Returns a `WebhookDetails`.
+
+ :http:statuscode:`404 Not found`:
+ The webhook(ID) is unknown to the backend.
+
+
+ .. ts:def:: WebhookDetails
+
+ interface WebhookDetails {
+
+ // The event of the webhook: why the webhook is used.
+ event_type: string;
+
+ // URL of the webhook where the customer will be redirected.
+ url: string;
+
+ // Method used by the webhook
+ http_method: string;
+
+ // Header template of the webhook
+ header_template?: string;
+
+ // Body template by the webhook
+ body_template?: string;
+
+ }
+
+
+Removing webhook
+-----------------
+
+.. http:delete:: [/instances/$INSTANCES]/private/webhooks/$WEBHOOK_ID
+
+ This is used to delete information about a webhook.
+
+ **Response:**
+
+ :http:statuscode:`204 No content`:
+ The backend has successfully deleted the webhook.
+
+ :http:statuscode:`404 Not found`:
+ The webhook(ID) or the instance is unknown to the backend.
+
+
+
------------------
The Contract Terms
------------------
diff --git 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/design-documents/033-database.rst b/design-documents/033-database.rst
@@ -0,0 +1,152 @@
+Database Schema and Versioning
+##############################
+
+Summary
+=======
+
+This document describes how we version database schema in GNU Taler
+and enable migrations.
+
+
+Motivation
+==========
+
+As Taler evolves, it will be necessary to add new tables, change existing
+tables, modify indices and make other changes to the database schema. As
+production systems exist, existing data will need to be migrated to the new
+schema, and we need to do this in a systematic way. While certain major
+changes may require radical or manual interventions, we should have a
+systematic way of dealing with minor or modest modifications to the schema.
+
+
+Requirements
+============
+
+* The approach should be language-independent
+* Schema migration should be reasonably performant
+* Schema migration must be usable, and in particular safe to use for
+ operators without significant risk
+* We need to support key database features we might need to use,
+ such as partitioning or sharding
+
+
+Proposed Solution
+=================
+
+We use the "versioning.sql" system to store the current set of patches that
+have been applied to the database so far in a "_v" schema. This allows us to
+quickly test which version of the database we are on and which migrations may
+still need to be applied.
+
+For each component, all tables are placed into a SCHEMA named after the
+component.
+
+We then use a set of numbered SQL files that create, alter or drop tables and
+indices (like exchange-0001.sql, exchange-0002.sql, ...) to setup the
+database. However, some setups need additional arguments, such as the number
+of partitions. Those setups are then NOT performed explicitly, but by creating
+stored procedures and registering those stored procedures in a general global
+"master" table to be called from the main setup logic with arguments in a
+particular order under certain conditions.
+
+When setting up a database, there is no point in incrementally defining
+ordinary stored procedures that are used at runtime (not the ones to setup the
+tables we talked about above). Thus, all of the stored procedures used by the
+runtime system are placed in a file "procedures.sql" which is loaded
+last. This makes changes to stored procedures particularly easy, as one simply
+edits "procedures.sql". Loading "procedures.sql" also does not change "_v".
+
+A "drop.sql" file is created that DROPs the main SCHEMA of the component and
+additionally unregisters all patches from the "_v" schema. The drop script
+is run during tests to fully reset the database.
+
+Exchange details
+^^^^^^^^^^^^^^^^
+
+The exchange uses "exchange_tables" to create the master
+table mentioned above. In "exchange_tables", entries are
+executed in the order of the "table_serial_id". Each
+entry has a "name", which is the name of the affected table
+(or at least the prefix in the case of partitioned or sharded
+tables). The "version" field stores which "exchange-XXXX.sql"
+file setup the respective table entry, but is for now mostly
+for internal documentation. The "action" defines both the
+condition under which to run a function. Specifically,
+actions can be:
+
+* create --- run on the master table and each shard; used to create or alter the main table
+* constrain --- run only on the partitions/shards, or on master if there are no partitions; used to setup constraints like uniqueness that only apply to the lowest levels of the table
+* master -- run only on the master table; used to setup triggers and other constraints that only apply to the master table
+* foreign -- run only on the master table and only if there are no partition; used to setup foreign key constraints that are not supported on partitioned or sharded tables
+
+The "partitioned" field indicates that this table is partitioned and instructs the functions to create partitions (or shards)
+for this table.
+
+The "by_range" field indicates if the table is partitioned by
+range, which prevents automatic generation of partitions as
+is done if partitioned by hash.
+
+The "finished" field is initially false, but set to TRUE once the respective
+function has been executed.
+
+The main "do_create_tables" function triggers the unfinished actions
+registered in the "exchange_tables" table. It is given arguments to control
+the number of partitions, the use of partitions and (in the future) the use of
+sharding.
+
+The individual actions use helper functions ("create_partitioned_table",
+"comment_partitioned_table" and "comment_partitioned_column") to facilitate
+the creation of tables and associated comments. These functions are used so
+that we can only define the schema or comment once, and have it applied to
+tables with names and creation syntax that changes slightly if we use shards
+or partitions.
+
+Some additional logic will be needed to deal nicely with
+sharding (which is currently not supported), as with
+sharing we will need to detach shards, migrate shards, and
+re-attach shards. So this will require additional stored
+procedures to support operations on shards.
+
+
+Merchant details
+^^^^^^^^^^^^^^^^
+
+The merchant does not (yet) need any type of master table, as we do not
+(yet) use any kind of sharding or partitioning. There are also no
+stored procedures being used by the backend. Hence, it is simply the
+"versioning.sql"-controlled table creation/alteration sequence
+(merchant-0001.sql, etc.) and the "drop.sql" to reset everything.
+
+
+Alternatives
+============
+
+* We might want to consider storing more meta-data
+ in the database, such as the use of sharding, the
+ names of the shard servers, or even just the number
+ of partitions.
+
+* We could require dumping out the old database and
+ loading it in via some explicit importer during each
+ migration; having migration logic in C would enable more
+ powerful migrations, but dumping and reloading the entire
+ database would also be more expensive. It would have the
+ advantage of basically having the old database around in
+ case of migration trouble, so the cost disadvantage might
+ not be so bad (as admins are likely to make a backup anyway).
+ OTOH, doing the migration with the equivalent of a
+ taler-auditor-sync would require quite a bit more code
+ than the simple ALTER/CREATE statements in an SQL file.
+
+
+Drawbacks
+=========
+
+* not exactly trival logic
+* some complexity to implement
+
+
+Discussion / Q&A
+================
+
+(This should be filled in with results from discussions on mailing lists / personal communication.)
diff --git a/libeufin/api-sandbox-future.rst 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
@@ -2,95 +2,95 @@
.. _sandbox-api:
-Current Sandbox API
-###################
+Sandbox API
+###########
-..
- Current Sandbox endpoints.
+Demobanks.
+==========
- GET /
- Welcome message.
+Sandbox is designed to allow multiple *demobanks* 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 segment ``/demobanks/default``, under which several
+APIs are then served. The following sections describe all such APIs.
- ** Camt debug **
+Access API.
+^^^^^^^^^^^
- POST /admin/payments/camt
- give last statement of requesting account
+Every endpoint is served under ``/demobanks/default/access-api``.
+See :doc:`/core/api-bank-access`. This API offers *users management*.
- ** Bank accounting **
+Integration API.
+^^^^^^^^^^^^^^^^
- POST /admin/bank-accounts/$accountLabel
- create bank account (no EBICS involved)
+Every endpoint is served under ``/demobanks/default/integration-api``.
+See :doc:`/core/api-bank-integration`. This API handles the communication
+with Taler wallets.
- GET /admin/bank-accounts
- Give summary of all the bank accounts.
+Taler Wire Gateway API.
+^^^^^^^^^^^^^^^^^^^^^^^
- GET /admin/bank-accounts/$accountLabel
- give general information about a bank account
+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, but the rest of
+this API does never involve the Sandbox.
- ** 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 API.
+^^^^^^^^^^
- ** EBICS subscribers management **
+.. _demobank-create-ebics-subscriber:
- POST /admin/ebics/subscribers
- Create a new EBICS subscriber.
+.. http:post:: /demobanks/default/ebics/subscribers
- GET /admin/ebics/subscribers
- Give details of all the EBICS subscribers in the bank.
+ Allows (only) the *admin* user to associate a bank account
+ to a EBICS subscriber. If the latter does not exist, it is
+ created.
- POST /admin/ebics/bank-accounts
- Create a *new* bank account and link it with an existing
- EBICS subscriber.
+ **Request:**
- ** EBICS host management **
+ .. ts:def:: SubscriberRequest
- POST /admin/ebics/hosts/$hostID/rotate-keys
- Change the bank's keys used in EBICS communication.
+ interface SubscriberRequest {
- POST /admin/ebics/hosts
- Create a new EBICS host.
+ // hostID
+ hostID: string;
- GET /admin/ebics/hosts
- Show details of all the EBICS hosts in the bank.
+ // userID
+ userID: string;
- ** EBICS serving **
+ // partnerID
+ partnerID: string;
- POST /ebicsweb
- Processes a EBICS request.
+ // systemID, optional.
+ systemID: string;
- ** Taler .. **
+ // Label of the bank account to associate with
+ // this subscriber.
+ demobankAccountLabel: string;
+ }
- GET /taler
- Show one taler://-URI to initiate a withdrawal.
+.. note::
- - Taler integration API.
+ The following endpoints are **not** served under the ``/demobank/default`` segment.
- - Demobank configuration API.
- ToDo.
+Legacy API.
+===========
- - Taler access API.
- ToDo.
+This was the first API offered by Sandbox. It is used in
+some test cases. One is hosted at the Wallet repository; other
+MAY as well exist.
-EBICS.
-^^^^^^
+Except of the main EBICS handler located at "/ebicsweb", all
+the EBICS calls have to authenticate the 'admin' user via
+the HTTP basic auth scheme.
-Hosts.
-++++++
+EBICS Hosts.
+^^^^^^^^^^^^
.. http:post:: /admin/ebics/hosts
- Creates a new Ebics host.
+ Create a new EBICS host.
**Request:**
@@ -128,9 +128,8 @@ Hosts.
meant for tests (as the Sandbox itself is) and no backup will be
produced along this operation.
-
-Subscribers.
-++++++++++++
+EBICS Subscribers.
+^^^^^^^^^^^^^^^^^^
.. http:post:: /admin/ebics/bank-accounts
@@ -143,7 +142,11 @@ Subscribers.
interface BankAccountRequest {
// Ebics subscriber
- subscriber: string;
+ subscriber: {
+ userID: string;
+ partnerID: string;
+ systemID: string;
+ };
// IBAN
iban: string;
@@ -157,39 +160,13 @@ Subscribers.
// 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, optional.
- systemID: string;
+ // Customer username that owns the bank account.
+ // Currency policy only allows same-named usernames
+ // and bank accounts.
+ owner: 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.
- demobankAccountLabel: string;
}
-
.. http:get:: /admin/ebics/subscribers
Shows the list of all the subscribers in the system.
@@ -221,209 +198,213 @@ 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.
^^^^^^^^^^^^^^
+The access to a particular bank account is granted either to the
+owner or to admin, via the HTTP basic auth scheme. A 'owner' is
+a registered customer, who is identified by a username. The
+registration of customers is offered via the :doc:`/core/api-bank-access`.
+
+.. note::
+
+ The current version allows only one bank account per
+ customer, where the bank account name (also called 'label')
+ equals the owner's username.
+
.. http:get:: /admin/bank-accounts
- Give summary of all the bank accounts.
+ Give summary of all the bank accounts. Only admin allowed.
-.. http:get:: /admin/bank-accounts/$accountLabel
+ **Response:**
- Give information about a bank account.
+ .. ts:def:: AdminBankAccount
-.. http:delete:: /demobanks/$demobankId/$accountLabel
+ interface AdminBankAccount {
- Delete the bank account (and the customer entry) from the database.
- Note, customer usernames and bank accounts have the same value.
+ // IBAN
+ iban: string;
-Main EBICS service.
-^^^^^^^^^^^^^^^^^^^
+ // BIC
+ bic: string;
-.. http:post:: /ebicsweb
+ // human name
+ name: string;
- Serves all the Ebics requests.
+ // bank account label
+ label: string;
+ }
-Transactions.
-^^^^^^^^^^^^^
+.. http:get:: /admin/bank-accounts/$accountLabel
-JSON.
-+++++
+ Give information about a bank account.
-.. http:get:: /admin/bank-accounts/$accountLabel/transactions
+ **Response:**
- Inform about all the transactions of one bank account.
+ .. ts:def:: AdminBankAccountBalance
-.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions
+ interface AdminBankAccountBalance {
+ // Balance in the $currency:$amount format.
+ balance: string;
+ // IBAN of the bank account identified by $accountLabel
+ iban: string;
+ // BIC of the bank account identified by $accountLabel
+ bic: string;
+ // Mentions $accountLabel
+ label: string;
+ }
- Generate one incoming and one outgoing transaction for one bank account.
+.. http:post:: /admin/bank-accounts/$accountLabel
-.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
+ Create bank account. Existing users without a bank account
+ can request too.
- Book one incoming transaction for $accountLabel.
- The debtor (not required to be in the same bank)
- information is taken from the request.
+ **Request:** :ts:type:`AdminBankAccount`
+Transactions.
+^^^^^^^^^^^^^
-Camt.
-+++++
+.. http:get:: /admin/bank-accounts/$accountLabel/transactions
-.. http:post:: /admin/payments/camt
+ Inform about all the transactions of one bank account.
- Return the last statement of the requesting account.
+ **Response:**
- **Request**
+ .. ts:def:: AdminTransactions
+
+ interface AdminTransactions {
+ payments: AdminTransaction[];
+ }
- .. code-block:: tsref
+ .. ts:def:: AdminTransaction
+
+ interface AdminTransaction {
- interface CamtParams {
+ // Label of the bank account involved in this payment.
+ accountLabel: string;
- // label of the bank account being queried.
- bankaccount: string;
+ // Creditor IBAN
+ creditorIban: string;
- // The Camt type to return. Only '53' is allowed
- // at this moment.
- type: number;
- }
+ // Debtor IBAN
+ debtorIban: string;
- **Response**
+ // UID given by one financial institute to this payment.
+ // FIXME: clarify whether that can be also assigned by
+ // the other party's institution.
+ accountServicerReference: string;
- The expected Camt.053 document.
+ // ID of the Pain.001 that initiated this payment.
+ paymentInformationId: string;
-Future Sandbox API
-##################
+ // Unstructured remittance information.
+ subject: string;
-Resources.
-^^^^^^^^^^
+ // Date of the payment in the HTTP header format.
+ date: string;
-Sandbox serves the following resources:
+ // The number amount as a string.
+ amount: string;
- - Demobanks.
- - Bank accounts.
- - Subscribers.
- - Transactions.
- - Customers.
- - Reports.
+ // BIC of the creditor IBAN.
+ creditorBic: string;
-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.
+ // Legal name of the creditor.
+ creditorName: string;
-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.
+ // BIC of the debtor IBAN.
+ debtorBic: string;
-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.
+ // Legal name of the debtor.
+ debtorName: string;
-.. note::
+ // Payment's currency
+ currency: string;
- ``POST``\ ing to an endpoint with a trailing ``$id`` means
- modification of an existing resource.
+ // Have values 'credit' or 'debit' relative
+ // to the requesting user.
+ creditDebitIndicator: string;
+ }
-Demobanks
-^^^^^^^^^
+.. http:post:: /admin/bank-accounts/$accountLabel/generate-transactions
-Demobanks are the main containers of all the other resources.
-They take configuration values, like the currency for example.
+ Generate one incoming and one outgoing transaction for the bank account
+ identified by ``$accountLabel``. Only admin allowed.
-.. http:get:: /admin/demobanks
-.. http:get:: /admin/demobanks/$id
-.. http:post:: /admin/demobanks
-.. http:post:: /admin/demobanks/$id
-.. http:delete:: /admin/demobanks/$id
+.. http:post:: /admin/bank-accounts/$accountLabel/simulate-incoming-transaction
-Bank accounts.
-^^^^^^^^^^^^^^
+ Book one incoming transaction for $accountLabel.
+ The debtor (not required to be in the same bank)
+ information is taken from the request. Only admin allowed.
-Bank accounts collect money of customers and participate
-in transactions.
+ **Request:**
+
+ .. ts:def:: AdminSimulateTransaction
-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.
+ interface AdminSimulateTransaction {
-.. http:get:: $base/bankaccounts
-.. http:get:: $base/bankaccounts/$id
-.. http:post:: $base/bankaccounts
-.. http:post:: $base/bankaccounts/$id
-.. http:delete:: $base/bankaccounts/$id
+ // Debtor IBAN.
+ debtorIban: string;
-Subscribers.
-^^^^^^^^^^^^
+ // Debtor BIC.
+ debtorBic: string;
-Subscribers are (optional) customers identities for protocols
-other than the native one.
+ // Debtor name.
+ debtorName: string;
-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.
+ // Amount number (without currency) as a string.
+ amount: string;
-.. note::
+ // Payment subject.
+ subject: string;
+ }
- 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
+.. http:post:: /admin/payments/camt
-Transactions.
-^^^^^^^^^^^^^
+ Return the last camt.053 document from the requesting account.
-Transactions are money movements between bank accounts.
+ **Request**
-For convenience, ``$base`` **could** mention one bank account
-to let customers see their transactions without defining "history"
-query parameters: like ``$demobank/bankaccounts/$bankaccountId/transactions``.
+ .. code-block:: tsref
-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.
+ interface CamtParams {
-.. http:get:: $base/transactions
-.. http:get:: $base/transactions/$id
-.. http:post:: $base/transactions
-.. http:post:: $base/transactions/$id
-.. http:delete:: $base/transactions/$id
+ // label of the bank account being queried.
+ bankaccount: string;
-Customers.
-^^^^^^^^^^
+ // The Camt type to return. Only '53' is allowed
+ // at this moment.
+ type: number;
+ }
+
+ **Response**
-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.
diff --git a/manpages/taler-merchant-httpd.1.rst b/manpages/taler-merchant-httpd.1.rst
@@ -13,6 +13,7 @@ Synopsis
========
**taler-merchant-httpd**
+[**-a**_|_**--auth**]
[**-C** | **--connection-close**]
[**-c** *FILENAME* | **--config=**\ \ *FILENAME*]
[**-h** | **--help**]
@@ -33,9 +34,9 @@ Options
=======
**-a** *TOKEN* \| **--auth=**\ \ *TOKEN*
- Use TOKEN for initial access control to the merchant backend. The value
+ Use TOKEN for initial access control to the merchant backend. TOKEN must start with the "secret-token:" prefix, as per RFC 8959. The value
given in TOKEN must appear in backoffice requests to the default instance
- of the merchant, i.e. "Authorization: Bearer secret-token:TOKEN" to obtain
+ of the merchant, i.e. "Authorization: Bearer TOKEN" to obtain
access to the merchant backend. Note that setting a passphrase for the
default instance by any means will block future access via TOKEN. This
is basically a way to reset the passphrase protecting access. TOKEN
diff --git a/manpages/taler.conf.5.rst b/manpages/taler.conf.5.rst
@@ -340,6 +340,10 @@ AGGREGATOR_SHIFT
Delay between a deposit being eligible for aggregation and
the aggregator actually triggering.
+DEFAULT_PURSE_LIMIT
+ Number of concurrent purses that a reserve may have active
+ if it is paid to be opened for a year.
+
EXCHANGE POSTGRES BACKEND DATABASE OPTIONS
------------------------------------------
diff --git a/taler-developer-manual.rst b/taler-developer-manual.rst
@@ -295,12 +295,21 @@ Demo Upgrade Procedure
#. Navigate to the ``deployment.git/docker/demo`` directory.
#. Refer to the README, or the smaller cheat sheet below.
-The deployment is based on rootless Docker, that is
-a SystemD unit in userspace: ``docker.service``. The
-running daemon is reached by every Docker command at the
-address held into the ``DOCKER_HOST`` environment variable.
-Normally, it points to ``unix:///run/user/$(id -u)/docker.sock``.
-Such variable is automatically exported by ``~/.bashrc``.
+The deployment is based on rootless Docker, managed by the
+SystemD unit in userspace: ``docker.service``. The running daemon
+is reached by every Docker command at the address held into the
+``DOCKER_HOST`` environment variable. Normally, it points to
+``unix:///run/user/$(id -u)/docker.sock``. Such variable is automatically
+exported by ``~/.bashrc``.
+
+.. note::
+
+ Should the rootless Docker be installed, run the following command
+ or consult the `official documentation <https://docs.docker.com/engine/security/rootless/>`_.
+
+ .. code-block:: console
+
+ $ curl -fsSL https://get.docker.com/rootless | sh
Upgrading the ``demo`` environment should be done with care, and ideally be
coordinated on the mailing list before. It is our goal for ``demo`` to always
@@ -383,14 +392,35 @@ Test builder
------------
This builder (``test-builder``) compiles and starts every Taler component.
-It is run by the ``taler-test`` Gv user.
+The associated worker is run by the ``taler-test`` Gv user, via the SystemD
+unit ``buildbot-worker-taler``. The following commands start/stop/restart
+the worker:
+
+.. code-block::
+
+ systemctl --user start buildbot-worker-taler
+ systemctl --user stop buildbot-worker-taler
+ systemctl --user restart buildbot-worker-taler
+
+.. note::
+ the mentioned unit file can be found at ``deployment.git/systemd-services/``
Wallet builder
--------------
This builder (``wallet-builder``) compiles every Taler component
-and runs the wallet integration tests. It is run by the ``walletbuilder``
-Gv user.
+and runs the wallet integration tests. The associated worker is
+run by the ``walletbuilder`` Gv user, via the SystemD unit ``buildbot-worker-wallet``.
+The following commands start/stop/restart the worker:
+
+.. code-block::
+
+ systemctl --user start buildbot-worker-wallet
+ systemctl --user stop buildbot-worker-wallet
+ systemctl --user restart buildbot-worker-wallet
+
+.. note::
+ the mentioned unit file can be found at ``deployment.git/systemd-services/``
Documentation Builder
---------------------
