libeufin docs

2 files changed, 79 insertions, 88 deletions

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 681811aa..f175c9d9 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -36,7 +36,7 @@ Users Management
 
 .. http:post:: <nexus>/users
 
-  Create a new user.  Only the super-user can call this API.
+  Create a new user.  Only a superuser can call this API.
 
   **Request:**
 
@@ -59,6 +59,11 @@ Users Management
        password: string;
      }
 
+
+.. http:get:: <nexus>/users
+
+  Return list of users.
+
 Bank Account Management
 -----------------------
 
@@ -95,27 +100,13 @@ Bank Account Management
        // to submit at the bank.
        uuid: string;
 
-       // Specify the bank transport to use for the submission.
-       transport?: Transport;
+       // Specify the bank connectionto use for the submission.
+       connection?: string;
      }
 
     
-  .. ts:def:: Transport
-
-     interface Transport {
-
-       // Transport type: 'ebics', 'local', 'fints' (forthcoming).
-       // It must match one of the types actually implemented by
-       // nexus.
-       type: string;
-
-       // A mnemonic identifier given by the user to one particular
-       // transport instance.
-       name: string;
-     }
-
   :status 404 Not Found: the unique identifier **or**
-    the bank transport could not be found in the system
+    the bank connection could not be found in the system
 
 
 .. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payments/$uuid
@@ -193,16 +184,16 @@ Bank Account Management
 
 .. http:post:: <nexus>/bank-accounts/collected-transactions
 
-  Nexus will download bank transactions from the given transport.
+  Nexus will download bank transactions using the given connection.
 
   **Request:**
 
   .. ts:def:: CollectedTransaction
 
      interface CollectedTransaction {
-       // Optional field to specify the bank transport to
+       // Optional field to specify the bank connection to
        // use for such operation.
-       bankTransport?: Transport;
+       bankConnection: connection;
        // dashed date (YYYY-MM-DD) of the earliest payment
        // in the result. Optional, defaults to "earliest
        // possible" date.
@@ -254,57 +245,58 @@ Bank Account Management
        subject: string;
      }
 
-Bank Transports
+
+Bank Connections
 ---------------
 
-Bank transports connect the local LibEuFin bank account
+Bank connections connect the local LibEuFin bank account
 to the real bank.
 
-.. http:post:: <nexus>/bank-transports
+.. http:post:: <nexus>/bank-connections
   
-  Activate a new bank transport for the requesting user.
+  Activate a new bank connection for the requesting user.
 
   **Request:**
 
-  .. ts:def:: BankTransport
+  .. ts:def:: BankConnectionRestoreRequest
 
-     interface BankTransport {
+     interface BankConnectionRestoreRequest {
 
-       transport: Transport;
+       name: string;
 
-       // Restore a previous transport.  Take precedence
+       // Restore a previous connection.  Take precedence
        // over the 'new' field.
-       backup?: TransportBackup;
+       backup?: BankConnectionBackup;
        
-       // Data to create a fresh bank transport without
+       // Data to create a fresh bank connection without
        // restoring any backup.
-       data?: TransportNew;
+       data?: BankConnectionNew;
      }
 
 
-  .. ts:def:: TransportNew
+  .. ts:def:: ConnectionNew
 
-     interface TransportNew {
+     interface ConnectionNew {
 
        // This type is strictly dependent on
-       // the transport being created.  For Ebics,
+       // the connection being created.  For Ebics,
        // it will contain the required fields (as strings):
        // 'ebicsURL', 'userID', 'partnerID', 'hostID', and
        // the optional 'systemID'.
   
-       // Other transport types, like 'local' (used for testing
+       // Other connection types, like 'local' (used for testing
        // purposes skipping any interaction with the bank service)
        // and 'fints' are all work in progress!
 
      }
 
 
-  .. ts:def:: TransportBackup
+  .. ts:def:: BankConnectionBackup
      
-     interface TransportBackup {
+     interface BankConnectionBackup {
 
        // The information needed in this type depend entirely
-       // on which transport is being restored.
+       // on which connectionis being restored.
 
      }
 
@@ -313,30 +305,29 @@ to the real bank.
   :status 409 Conflict: The ``name`` field exists already for
     the requesting user.
 
-.. http:post:: <nexus>/bank-transports/sendMSG.
-  
-  Perform the ``MSG`` operation offered by ``transport-name``
-  **without** affecting the nexus database.
 
-  **Request:**
-  
-  A `Transport` object.
+.. http:post:: <nexus>/bank-connections
 
-  **Response:**
+   List available bank connections.
 
-  :status 404 Not Found: ``transport-name`` doesn't exist for
-    the requesting user.
 
-.. http:post:: <nexus>/bank-transports/<transport-name>/syncMSG.
-  
-  Some transports **do** have operations that aren't semantically
-  related to a bank account but need to be stored locally at the nexus.
-  One typical example is the downloading of the bank's keys vie the
-  EBICS transport.  This API lets the user perform the ``MSG``
-  operation that should result in new data being stored locally
-  at the nexus.
+EBICS-specific APIs
+-------------------
 
-  **Response:**
+The following endpoints are only available for EBICS bank connections.
+They are namespaced under the ``/ebics/`` sub-resource.
 
-  :status 404 Not Found: ``transport-name`` doesn't exist for
-    the requesting user.
+.. http:post:: <nexus>/bank-connections/<connection-name>/ebics/download/<msg>
+
+  
+  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:: <nexus>/bank-connections/<connection-name>/ebics/upload/<msg>
+  
+  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
+  and return the answer.
diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst
index 00afe9a6..da48d7f8 100644
--- a/libeufin/concepts.rst
+++ b/libeufin/concepts.rst
@@ -57,42 +57,42 @@ The information stored about it includes:
   with their state (sent or not sent, acknowledged in bank statement or not).
 * Error reports (e.g. failed payment requests, bank statement items that were not understood
   by LibEuFin)
-* A default bank transport (if configured) that is used by default
+* A default bank connection (if configured) that is used by default
   for operations on the account
-* Other connected bank transports
+* Other enabled bank connections
 
 Examples:
 
 .. code:: none
 
-  # Download latest transactions via the default bank transport and store them locally
+  # Download latest transactions via the default bank connection and store them locally
   curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-accounts/my-acct/collect-transactions
 
-Bank Transports
----------------
+Bank Connections
+----------------
 
-Bank transports connect the local LibEuFin bank account to the real bank.
-The bank transport includes the following data:
+Bank connections connect the local LibEuFin bank account to the real bank.
+The bank connection includes the following data:
 
-* Local alias ("nickname") of the bank transport
-* the type of transport (EBICS, FinTS, loopback, sandbox)
-* credentials to use the transport (e.g. password, EBICS subscriber keys)
+* Local alias ("nickname") of the bank connection
+* the type of connection, i.e. the protocol used (EBICS, FinTS, loopback, sandbox)
 * protocol configuration (hostname, port, protocol sub-version/flags)
+* credentials to use the connection (e.g. password, EBICS subscriber keys)
 
-Bank transports provide the following actions:
+Bank connections provide the following actions:
 
-* Initial setup of the transport
+* Initial setup of the connection
 
 * Execute protocol-specific actions (e.g. EBICS: C53, C52, CCT, CRZ)
 
   * These actions do not have any effect on the LibEuFin local bank account.
     To persist changes to the local bank account (transaction history, payment request status),
-    the bank transport must be invoked via the bank account.
+    the bank connection must be invoked via the bank account.
 
 * Import bank accounts
 
-  * Some bank transport protocols allow LibEuFin to query a list of bank
-    accounts that the transport has access to.  This makes setup easier,
+  * Some bank connection protocols allow LibEuFin to query a list of bank
+    accounts that the connection has access to.  This makes setup easier,
     as the user doesn't have to create the local bank account manually.
 
 Examples:
@@ -100,22 +100,22 @@ Examples:
 .. code:: none
 
   # Manually request the inter-day account report via the EBICS C52 order
-  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-transports/my-ebics-testacct/send-c52
+  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connections/my-ebics-testacct/send-c52
 
-  # Download available bank accounts that can be accessed through this transport,
+  # Download available bank accounts that can be accessed through this connection,
   # according to the bank server (with EBICS, does a HTD request).
   # For each of them, create a bank account resource in LibEuFin.
-  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-transports/my-ebics-testacct/import-accounts
+  curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connection/my-ebics-testacct/import-accounts
 
 Facades
 -------
 
 Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts
-and bank transports.  Facades store the following information:
+and bank connections.  Facades store the following information:
 
 * Local name of the facade
 * Facade type and options specific to the type
-* Associated bank accounts and bank transports that can be accessed by the layer
+* Associated bank accounts and bank connections that can be accessed by the layer
 * Internal tables used by the facade (i.e. facades are stateful)
 
 The only facade currently supported by LibEuFin is the "Taler Wire Gateway API" layer.
@@ -135,7 +135,7 @@ Access Control
 
 The goal of access control in LibEuFin is to allow the following scenarios:
 
-* The Nexus can be used by multiple clients for different bank accounts/transports,
+* The Nexus can be used by multiple clients for different bank accounts/connections
   and these users can't access each other's bank accounts
 * For monitoring / dashboard (e.g. Taler rejected transactions, blacklists),
   some users should only be able to have read-only access.
@@ -146,15 +146,15 @@ spending limits or more fine-grained read/write permissions.
 Users can be normal users or superusers.  Permission checks do not apply to superusers,
 and only superusers can create other users.
 
-Each top-level object (bank account, bank transport, layer) has a list of
+Each top-level object (bank account, bank connection, facade) has a list of
 nexus users with write access, and a list of users with read access.
 
-When using a bank transport through a bank account, permission checks must
-succeed for both the bank account and the bank transport.
+When using a bank connection through a bank account, permission checks must
+succeed for both the bank account and the bank connection
 
-This works differently for layers:  A layer has a set of associated bank transports
+This works differently for facades:  A facade has a set of associated bank connections
 and bank accounts it can access.  Permissions on these associated objects
-are checked when the layer is *created*.  When invoking operations on the layer,
-the nexus only checks if the current nexus user can access the layer and *not* the
-underlying objects abstracted by the layer.
+are checked when the facade is *created*.  When invoking operations on the facade,
+the nexus only checks if the current nexus user can access the facade and *not* the
+underlying objects abstracted by the facade.