[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[taler-docs] 02/02: finishing pass over nexus API
From: |
gnunet |
Subject: |
[taler-docs] 02/02: finishing pass over nexus API |
Date: |
Mon, 20 Mar 2023 09:23:45 +0100 |
This is an automated email from the git hooks/post-receive script.
ms pushed a commit to branch master
in repository docs.
commit 7fa5f82998932fab827797dba5d302ace551db11
Author: ms <ms@taler.net>
AuthorDate: Sun Mar 19 22:56:48 2023 +0100
finishing pass over nexus API
---
libeufin/api-nexus.rst | 122 +++++++++++++++----------------------------------
1 file changed, 38 insertions(+), 84 deletions(-)
diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 998f6b3..2ec9032 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -861,8 +861,8 @@ Facades
config: any;
}
- For "taler-wire-gateway" and "anastasis" facades, ``config`` contains
- the following type:
+ For "taler-wire-gateway" and "anastasis" facades,
+ ``config`` contains the following type:
.. ts:def:: TalerAnastasisFacadeState
@@ -871,6 +871,9 @@ Facades
bankConnection: string;
// (Nexus local) bank account associated to this facade.
bankAccount: string;
+ // Whether the facade seeks reports or statements from the bank.
+ reserveTransferLevel?: string;
+ currency?: string;
}
.. http:delete:: {nexus}/facades/{fcid}
@@ -911,11 +914,11 @@ Bank Connection Protocols
.. http:get:: {nexus}/bank-connection-protocols
- List supported bank connection protocols.
+ Lists supported bank connection protocols.
.. http:post:: {nexus}/bank-connection-protocols/ebics/test-host
- Check if the nexus can talk to an EBICS host.
+ Check if Nexus can talk to an EBICS host.
This doesn't create a new connection in the database,
and is useful during setup when the user hasn't entered
the full details for the connection yet.
@@ -942,55 +945,42 @@ They are namespaced under the ``/ebics/`` sub-resource.
Perform an EBICS download transaction of type ``msg``.
This request will not affect any bank account or other state
- in the nexus database. It will just make a request to the bank
- and return the answer.
-
-.. http:post::
{nexusBase}/bank-connections/{connection-name}/ebics/upload/{msg}
-
- .. warning::
-
- Use with care. Typically only necessary for testing and debugging.
-
- Perform an EBICS upload transaction of type ``msg``.
- This request will not affect any bank account or other state
- in the nexus database. It will just make a request to the bank
+ in Nexus database. It will just make a request to the bank
and return the answer.
Anastasis API.
--------------
This is a read-only API offering a view over *only* the incoming
-transactions of a bank account. It is named after the typical user -
-a Anastasis service - but can be used in any case where only the
-incoming transactions are of interest.
+transactions of a bank account. The name comes from the use in
+`Anastasis <https://www.anastasis.lu>`_.
.. http:get:: ${BASE_URL}/history/incoming
- Return a list of transactions made to the customer.
-
- The bank account of the customer is determined via the base URL and/or the
- user name in the ``Authorization`` header. In fact the transaction history
- might come from a "virtual" account, where multiple real bank accounts are
- merged into one history.
+ Returns a list of transactions made to the customer.
- Transactions are identified by an opaque numeric identifier, referred to here
- as *row ID*. The semantics of the row ID (including its sorting order) are
- determined by the bank server and completely opaque to the client.
+ Transactions are identified by a numeric identifier,
+ that reflects the order in which Nexus downloaded each
+ transaction from the bank.
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
+ The list of returned transactions is determined by a row
+ ID *starting point* and a signed non-zero integer *delta*:
- * If *delta* is positive, return a list of up to *delta* transactions (all
matching
- the filter criteria) strictly **after** the starting point. The
transactions are sorted
+ * If *delta* is positive, returns a list of up to *delta*
+ transactions (all matching the filter criteria) strictly
+ **after** the starting point. The transactions are sorted
in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions (all
matching
- the filter criteria) strictly **before** the starting point. The
transactions are sorted
+ * If *delta* is negative, return a list of up to *-delta*
+ transactions (all matching the filter criteria) strictly
+ **before** the starting point. The transactions are sorted
in **descending** order of the row ID.
If *starting point* is not explicitly given, it defaults to:
- * A value that is **smaller** than all other row IDs if *delta* is
**positive**.
- * A value that is **larger** than all other row IDs if *delta* is
**negative**.
+ * A value that is **smaller** than all other row IDs if *delta*
+ is **positive**.
+ * A value that is **larger** than all other row IDs if *delta*
+ is **negative**.
**Request**
@@ -999,18 +989,24 @@ incoming transactions are of interest.
:query delta:
The *delta* value that determines the range of the query.
:query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to
``long_poll_ms``
+ result of the query would be empty, Nexus will wait up to ``long_poll_ms``
milliseconds for new transactions that match the query to arrive and only
then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
+ Nexus may return a response immediately or after waiting only a fraction
of ``long_poll_ms``.
**Response**
:http:statuscode:`200 OK`: JSON object of type `IncomingHistory`.
- :http:statuscode:`400 Bad request`: Request malformed. The bank replies with
an `ErrorDetail` object.
- :http:statuscode:`401 Unauthorized`: Authentication failed, likely the
credentials are wrong.
- :http:statuscode:`404 Not found`: The endpoint is wrong or the user name is
unknown. The bank replies with an `ErrorDetail` object.
+
+ :http:statuscode:`400 Bad request`: Request malformed. Nexus replies
+ with an `ErrorDetail` object.
+
+ :http:statuscode:`401 Unauthorized`: Authentication failed, likely
+ the credentials are wrong.
+
+ :http:statuscode:`404 Not found`: The endpoint is wrong or the user
+ name is unknown. Nexus replies with an `ErrorDetail` object.
.. ts:def:: IncomingHistory
@@ -1035,7 +1031,7 @@ incoming transactions are of interest.
amount: Amount;
// Payto URI to identify the receiver of funds.
- // This must be one of the exchange's bank accounts.
+ // Typically an exchange's bank accounts.
credit_account: string;
// Payto URI to identify the sender of funds.
@@ -1043,50 +1039,8 @@ incoming transactions are of interest.
// subject of the incoming payment.
subject: string;
-
}
-The anastasis facade
---------------------
-
-The ``anastasis`` facade has the following configuration:
-
-
-.. ts:def:: AnastasisFacadeConfig
-
- interface AnastasisFacadeConfig {
- // Bank account and connection that is abstracted over.
- bankAccount: string;
- bankConnection: string;
-
- currency: string;
-
- // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT)
- // for incoming transfers.
- reserveTransferLevel: "statement" | "report" | "notification";
- }
-
-The taler-wire-gateway facade
------------------------------
-
-The ``taler-wire-gateway`` facade has the following configuration:
-
-
-.. ts:def:: TalerWireGatewayFacadeConfig
-
- interface TalerWireGatewayFacadeConfig {
- // Bank account and connection that is
- // abstracted over.
- bankAccount: string;
- bankConnection: string;
-
- currency: string;
-
- // Corresponds to whether we trust C52, C53 or C54 (SEPA ICT)
- // for incoming transfers.
- reserveTransferLevel: "statement" | "report" | "notification";
- }
-
Reaching the facade
-------------------
--
To stop receiving notification emails like this one, please contact
gnunet@gnunet.org.