nexus API upgrade

2 files changed, 232 insertions, 1 deletions

diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst
new file mode 100644
index 00000000..0802cf07
--- /dev/null
+++ b/libeufin/api-nexus2.rst
@@ -0,0 +1,231 @@
+Nexus API
+###########
+
+HTTP API
+========
+
+Authentication
+--------------
+
+**Every** request made to nexus must be authenticated
+using the *HTTP basic auth* mechanism.
+
+Users Management
+----------------
+
+.. http:post:: <nexus>/users
+
+  Create a new user.  Only the super-user can call this API.
+
+  **Request:**
+
+  The body is a `User` object.
+
+  **Response:**
+
+  :status 409 Conflict: Username is not available.
+
+  **Details:**
+
+  .. ts:def:: User
+
+     interface User {
+
+       // User name
+       username: string;
+
+       // Shadow password
+       shadowPassword: string;
+     }
+
+Bank Account Management
+-----------------------
+
+.. http:get:: <nexus>/bank-accounts
+  
+  Return the list of bank accounts belonging to the requesting
+  user.
+
+  **Response:** A list of `BankAccount` objects.
+
+  .. ts:def:: BankAccount
+     
+     interface BankAccount {
+       // mnemonic name identifying this bank account.
+       account: string; 
+       // IBAN
+       iban: string;
+       // BIC
+       bic: string;
+       // Legal subject owning the account.
+       holder: string;
+     }
+
+.. http:post:: <nexus>/bank-accounts/<my-acct>/prepare-payment
+  
+  Ask nexus to prepare instructions for a new payment.  **The technique
+  to submit prepared payments at the bank is still work in progress!**
+  Note that ``my-acct`` is the bank account that will be **debited**
+  after this operation.
+
+.. There are (at least) two styles to specify the bank-transport
+.. to use: (1) we specify it here in a field the name of the bank-transport,
+.. or (2) we associate a ID to this prepared payment, and make another
+.. endpoint that accepts the payment's ID and the bank-transport to
+.. use for the submission.  Style (2) seems more flexible.
+
+  **Request:**
+    .. ts:def:: PreparedPayment
+
+      interface PreparedPayment {
+        // IBAN that will receive the payment.
+        iban: string;
+        // BIC hosting the IBAN.
+        bic: string;
+        // Legal subject that will receive the payment.
+        name: string;
+
+        // amount, in the format CURRENCY:XX.YY
+        amount: string
+      }
+
+  **Response:**
+
+  **Details:**
+
+.. http:post:: <nexus>/bank-accounts/<my-acct>/collect-transactions
+
+  Ask the default transport to download the latest transactions
+  and store them locally.
+
+  **Request:**
+    The request body is a `CollectTransactions` JSON object.
+    ``my-acct`` is the mnemonic identifier that any bank account
+    stored locally at the nexus has.  Typically, it is the real
+    bank that assigns such identifiers to the bank accounts.
+
+  **Details**
+
+  .. ts:def:: CollectTransactions
+
+     interface CollectTransactions {
+       // Optional field to specify the bank transport to
+       // use for such operation.
+       bankTransport: string;
+       // dashed date (YYYY-MM-DD) of the earliest payment
+       // in the result. Optional, defaults to "earliest
+       // possible" date.
+       start: string;
+       // dashed date (YYYY-MM-DD) of the earliest payment
+       // in the result. Optional, defaults to "latest
+       // possible" date.
+       end: string;
+     }
+
+.. http:post:: <nexus>/collected-transactions
+
+  Shows which transactions are stored locally at nexus.
+
+  **Request:**
+
+  .. ts:def:: TimeRange
+
+     interface TimeRange {
+       // start date of desired payments.  Optional,
+       // defaults to "earliest possible" date.
+       start: string;
+       // end date of desired payments.  Optional,
+       // defaults to "latest possible" date.
+       end: string;
+     }
+
+  **Response:** A list of `Transaction` objects.
+
+  .. ts:def:: Transaction
+
+     interface Transaction {
+       // local bank account involved in the transaction.
+       account: string;
+
+       // counterpart IBAN
+       counterpartIban: string;
+
+       // counterpart BIC
+       counterpartBic: string;
+
+       // counterpart holder name
+       counterpartName: string;
+
+       // amount, in the format [-]CURRENCY:XX.YY,
+       // where the minus sign as prefix indicates
+       // a debit for the user's bank account.
+       amount: string
+     }
+
+Bank Transports
+---------------
+
+Bank transports connect the local LibEuFin bank account
+to the real bank.
+
+.. http:post:: <nexus>/bank-transports
+  
+  Activate a new bank transport for the requesting user.
+
+  **Request:**
+  Object of the type `BankTransport`
+
+  **Response:**
+
+  :status 409 Conflict: The ``name`` field exists already for
+    the requesting user.
+
+  **Details:**
+
+  .. ts:def:: BankTransport
+
+     interface BankTransport {
+
+       // Mnemonic identifier for the transport bein created.
+       name: string;
+
+       // Optional field to restore a previous transport.
+       backup: TransportBackup;
+
+       // Type of the transport (ebics, fints, native, ..)
+       type: string;
+     }
+
+
+  .. ts:def:: TransportBackup
+     
+     interface TransportBackup {
+
+      // The information needed in this type depend entirely
+      // on which transport is being restored.
+
+     }
+
+.. http:post:: <nexus>/bank-transports/<transport-name>/sendMSG.
+  
+  Perform the ``MSG`` operation offered by ``transport-name``
+  **without** affecting the nexus database.
+
+  **Response:**
+
+  :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.
+
+  **Response:**
+
+  :status 404 Not Found: ``transport-name`` doesn't exist for
+    the requesting user.
diff --git a/libeufin/index.rst b/libeufin/index.rst
index 9dc62685..ea3c7aa3 100644
--- a/libeufin/index.rst
+++ b/libeufin/index.rst
@@ -10,5 +10,5 @@ LibEuFin is a project providing free software tooling for European FinTech.
   ebics
   architecture
   api-sandbox
-  api-nexus
+  api-nexus2
   iso20022