finishing pass over nexus API

1 files changed, 38 insertions, 84 deletions

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 998f6b3b..2ec90322 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
 -------------------