[taler-docs] branch master updated (a4a1a6b -> 7fa5f82)

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a change to branch master
in repository docs.

    from a4a1a6b  making formulation more abstract
     new e6a667d  pass over facade API
     new 7fa5f82  finishing pass over nexus API

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 libeufin/api-nexus.rst | 157 +++++++++++++++++++------------------------------
 1 file changed, 60 insertions(+), 97 deletions(-)

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 91a3b5e..2ec9032 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -835,8 +835,7 @@ Facades
 
 .. http:get:: <nexus>/facades/{fcid}
 
-   **Response:** A `FacadeShowInfo` pointed to by ``fcid``.
-
+   **Response:** A `FacadeShowInfo` whose name is ``fcid``.
 
 .. http:get:: <nexus>/facades
 
@@ -862,13 +861,28 @@ Facades
       config: any;
     }
 
+  For "taler-wire-gateway" and "anastasis" facades,
+  ``config`` contains the following type:
+
+  .. ts:def:: TalerAnastasisFacadeState
+
+    interface TalerFacadeState {
+      // Bank connection this facade relies on.
+      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}
 
-  Delete a facade.
+  Deletes a facade.
 
 .. http:post:: {nexus}/facades
 
-  Create a new facade.
+  Creates a new facade.
 
   **Request:**
 
@@ -882,31 +896,29 @@ Facades
         // For example, "taler-wire-gateway" or "anastasis".
         type: string;
 
-        // Bank accounts that the facade has read/write
-        // access to.
-        bankAccountsRead: string[];
-        bankAccountsWrite: string[];
+        // Bank accounts that the facade has read/write access to.
+        bankAccountsRead?: string[];
+        bankAccountsWrite?: string[];
 
-        // Bank connections that the facade has read/write
-        // access to.
-        bankConnectionsRead: string[];
-        bankConnectionsWrite: string[];
+        // Bank connections that the facade has read/write access to.
+        bankConnectionsRead?: string[];
+        bankConnectionsWrite?: string[];
 
-        // Facade-specific configuration details.
-        config: any;
+        // Facade-specific configuration details.  Only the
+        // following type is available.
+        config: TalerAnastasisFacadeState;
      }
 
-
 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.
@@ -933,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**
 
@@ -990,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
 
@@ -1026,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.
@@ -1034,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.