rename file

2 files changed, 219 insertions, 406 deletions

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 745182cf..e96b6862 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -1,187 +1,300 @@
 Nexus API
 ###########
 
-
 HTTP API
 ========
 
+Authentication
+--------------
+
+Currently every request made to nexus must be authenticated using the *HTTP
+basic auth* mechanism.
+
+Other authentication mechanisms (e.g. OpenID Connect) might
+be supported in the future.
+
 Users Management
 ----------------
 
-Users are the entity that access accounts.  They do not necessarily correspond
-to the actual legal owner of an account.  Their main purpose in the nexus is
-access management.
+.. http:get:: <nexus>/user
 
-.. http:get:: <nexus>/users
+  Get information about the current user (based on the authentication information
+  in this request).
 
-  List users.
+  **Response:**
 
-  **Required permission:** Administrator.
+  .. ts:def:: GetUserResponse
+
+     interface UserResponse {
+
+       // User name
+       username: string;
+
+       // Is it a superuser?
+       superuser: boolean;
+     }
 
 .. http:post:: <nexus>/users
 
-  Create a new user.
+  Create a new user.  Only the super-user can call this API.
+
+  **Request:**
 
-  **Required permission:** Administrators.
+  The body is a `User` object.
 
+  **Response:**
+
+  :status 409 Conflict: Username is not available.
+
+  **Details:**
+
+  .. ts:def:: CreateUserRequest
+
+     interface User {
+
+       // User name
+       username: string;
+
+       // Initial password
+       password: string;
+     }
 
 Bank Account Management
 -----------------------
 
 .. http:get:: <nexus>/bank-accounts
+  
+  **Response:**
 
-  List bank accouts managed by nexus.
+  A list of `BankAccount` objects
+  that belong to the requester.
 
+  .. 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
+.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments/submit
 
-  List bank accouts managed by nexus.
+  Ask nexus to submit one prepare payment at the bank.
 
+  **Request:**
 
-.. http:get:: <nexus>/bank-accounts/{acctid}/history
+  .. ts:def:: SubmitPayment
 
-  :query method: Method to query the bank transaction (cached, ebics, fints, ...)
+     interface SubmitPayment {
+       // Unique identifier of the (previously) prepared payment
+       // to submit at the bank.
+       uuid: string;
 
-  Query the transaction history of an account via the specified method.
+       // Specify the bank transport to use for the submission.
+       transport?: string;
+     }
 
+  :status 404 Not Found: the unique identifier **or**
+    the bank transport could not be found in the system
 
-.. http:get:: <nexus>/bank-accounts/{acctid}/payments
 
-  List payments made with this bank account via nexus.
+.. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payments/$uuid
+   
+   Ask the status of payment ``$uuid``.
 
-.. http:post:: <nexus>/bank-accounts/{acctid}/payments
+   **Response:**
 
-  Initiate a payment.
+   .. ts:def:: PaymentStatus
 
+      interface PaymentStatus {
 
-Low-level EBICS API
--------------------
+        // Payment unique identifier
+        uuid: string;
 
-.. http:post:: <nexus>/ebics/subscribers/{id}/backup
-  
-  Ask the server to export the three keys, protected with passphrase.
+        // True for submitted payments
+        submitted: boolean;
 
-  .. ts:def:: NexusEbicsBackupRequest
-    
-    interface NexusEbicsBackupRequest {
-      passphrase: string;
-    }
+        // Creditor IBAN
+        creditorIban: string;
 
+        // Creditor BIC
+        creditorBic: string;
 
-  .. ts:def:: NexusEbicsBackupResponse
+        // Creditor legal name
+        creditorName: string;
 
-    interface NexusEbicsBackupResponse {
-      
-      // The three passphrase-protected private keys in the PKCS#8 format
+        // Amount
+        amount: string;
 
-      authBlob: string; // base64
-      encBlob: string; // base64
-      sigBlob: string; // base64
-      hostID: string;
-      userID: string;
-      partnerID: string;
-      ebicsURL: string;
-    }
+        // Date of submission (in dashed form YYYY-MM-DD)
+        submissionDate: string;
 
+        // Date of preparation (in dashed form YYYY-MM-DD)
+        preparationDate: string;
+      }
 
-.. http:post:: <nexus>/ebics/subscribers/{id}/restoreBackup
+.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments
   
-  Ask the server to restore the keys.  Always creates a NEW
-  "{id}" account, and fails if it exists already.
+  Ask nexus to prepare instructions for a new payment.
+  Note that ``my-acct`` is the bank account that will be
+  **debited** after this operation.
+
+  **Request:**
+
+  .. ts:def:: PreparedPaymentRequest
+
+     interface PreparedPaymentRequest {
+       // IBAN that will receive the payment.
+       iban: string;
+       // BIC hosting the IBAN.
+       bic: string;
+       // Legal subject that will receive the payment.
+       name: string;
+       // payment subject. 
+       subject: string;
+       // amount, in the format CURRENCY:XX.YY
+       amount: string
+     }
+
+  **Response:**
+
+  .. ts:def:: PreparedPaymentResponse
+     
+     interface PreparedPaymentResponse {
+
+       // Opaque identifier to be communicated when
+       // the user wants to submit the payment to the
+       // bank.
+       uuid: string;
+     }
 
-  .. ts:def:: NexusEbicsRestoreBackupRequest
+.. http:post:: <nexus>/bank-accounts/<my-acct>/collected-transactions
 
-    interface NexusEbicsRestoreBackupRequest {
-      
-      // passphrase to decrypt the keys
-      passphrase: string;
+  Ask the default transport to download the latest transactions
+  related to ``my-acct`` and store them locally.
 
-      // The three passphrase-protected private keys in the PKCS#8 format
-      authBlob: string; // base64
-      encBlob: string; // base64
-      sigBlob: string; // base64
-      hostID: string;
-      userID: string;
-      partnerID: string;
-      ebicsURL: string;
-    }
+  **Request:**
 
-  .. ts:def:: NexusEbicsCreateSubscriber
+  .. ts:def:: CollectedTransaction
 
-.. http:post:: <nexus>/ebics/subscribers
+     interface CollectedTransaction {
+       // 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;
+     }
 
-  Create a new subscriber.  Create keys for the subscriber that
-  will be used in later operations.
+.. http:get:: <nexus>/bank-accounts/<my-acct>/collected-transactions
 
-  .. ts:def:: NexusEbicsCreateSubscriber
+  Shows which transactions are stored locally at nexus.
 
-    interface NexusEbicsCreateSubscriber {
-      ebicsUrl: string;
-      hostID: string;
-      partnerID: string;
-      userID: string;
-      systemID: string?
-    }
+  **Query parameters:**
 
+  * **start** start (dashed YYYY-MM-DD) date of desired payments.
+    Optional, defaults to "earliest possible" date
+  * **end** end (dashed YYYY-MM-DD) date of desired payments.
+    Optional, defaults to "earliest possible" date
 
-.. http:get:: <nexus>/ebics/subscribers
 
-  List EBICS subscribers managed by nexus.
+  **Response:** A list of `Transaction` objects.
 
+  .. ts:def:: Transaction
 
-.. http:get:: <nexus>/ebics/subscribers/{id}
+     interface Transaction {
+       // local bank account involved in the transaction.
+       account: string;
 
-  Get details about an EBICS subscriber.
+       // counterpart IBAN
+       counterpartIban: string;
 
-.. http:get:: <nexus>/ebics/subscriber/{id}/keyletter
+       // counterpart BIC
+       counterpartBic: string;
 
-  Get a formatted letter (mark-down) to confirm keys via ordinary mail.
+       // counterpart holder name
+       counterpartName: string;
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sendIni
+       // amount, in the format [-]CURRENCY:XX.YY,
+       // where the minus sign as prefix indicates
+       // a debit for the user's bank account.
+       amount: string
+     }
 
-  Send INI message to the EBICS host.
+Bank Transports
+---------------
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sendHia
+Bank transports connect the local LibEuFin bank account
+to the real bank.
 
-  Send HIA message to the EBICS host.
+.. http:post:: <nexus>/bank-transports
+  
+  Activate a new bank transport for the requesting user.
+
+  **Request:**
+  Object of the type `BankTransport`
 
-.. http:get:: <nexus>/ebics/subscriber/{id}/sendHtd
+  **Response:**
 
-  Send HTD message to the EBICS host.
+  :status 409 Conflict: The ``name`` field exists already for
+    the requesting user.
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sync
+  **Details:**
 
-  Synchronize with the EBICS server.  Sends the HPB message
-  and updates the bank's keys.
+  .. ts:def:: BankTransport
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sendEbicsOrder
+     interface BankTransport {
 
-  Sends an arbitrary bank-technical EBICS order.  Can be an upload
-  order or a download order.
+       // Mnemonic identifier for the transport bein created.
+       name: string;
 
-  .. ts:def:: NexusEbicsSendOrderRequest::
+       // Optional field to restore a previous transport.
+       backup: TransportBackup;
 
-    interface NexusEbicsSendOrderRequest {
-      // Bank-technical order type, such as C54 (query transactions)
-      // or CCC (initiate payment)
-      orderType: string;
+       // Type of the transport (ebics, fints, native, ..)
+       type: string;
+     }
 
-      // Generic order parameters, such as a date range for querying
-      // an account's transaction history.
-      orderParams: OrderParams
 
-      // Body (XML, MT940 or whatever the bank server wants)
-      // of the order type, if it is an upload order
-      orderMessage: string;
-    }
+  .. ts:def:: TransportBackup
+     
+     interface TransportBackup {
 
+      // The information needed in this type depend entirely
+      // on which transport is being restored.
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/ebicsOrders
+     }
+
+.. http:post:: <nexus>/bank-transports/<transport-name>/sendMSG.
+  
+  Perform the ``MSG`` operation offered by ``transport-name``
+  **without** affecting the nexus database.
 
-  .. note::
+  **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.
 
-    This one should be implemented last and specified better!
+  **Response:**
 
-  Return a list of previously sent ebics messages together with their status.
-  This allows retrying sending a message, if there was a crash during sending
-  the message.
+  :status 404 Not Found: ``transport-name`` doesn't exist for
+    the requesting user.
diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst
deleted file mode 100644
index e96b6862..00000000
--- a/libeufin/api-nexus2.rst
+++ /dev/null
@@ -1,300 +0,0 @@
-Nexus API
-###########
-
-HTTP API
-========
-
-Authentication
---------------
-
-Currently every request made to nexus must be authenticated using the *HTTP
-basic auth* mechanism.
-
-Other authentication mechanisms (e.g. OpenID Connect) might
-be supported in the future.
-
-Users Management
-----------------
-
-.. http:get:: <nexus>/user
-
-  Get information about the current user (based on the authentication information
-  in this request).
-
-  **Response:**
-
-  .. ts:def:: GetUserResponse
-
-     interface UserResponse {
-
-       // User name
-       username: string;
-
-       // Is it a superuser?
-       superuser: boolean;
-     }
-
-.. 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:: CreateUserRequest
-
-     interface User {
-
-       // User name
-       username: string;
-
-       // Initial password
-       password: string;
-     }
-
-Bank Account Management
------------------------
-
-.. http:get:: <nexus>/bank-accounts
-  
-  **Response:**
-
-  A list of `BankAccount` objects
-  that belong to the requester.
-
-  .. 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>/prepared-payments/submit
-
-  Ask nexus to submit one prepare payment at the bank.
-
-  **Request:**
-
-  .. ts:def:: SubmitPayment
-
-     interface SubmitPayment {
-       // Unique identifier of the (previously) prepared payment
-       // to submit at the bank.
-       uuid: string;
-
-       // Specify the bank transport to use for the submission.
-       transport?: string;
-     }
-
-  :status 404 Not Found: the unique identifier **or**
-    the bank transport could not be found in the system
-
-
-.. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payments/$uuid
-   
-   Ask the status of payment ``$uuid``.
-
-   **Response:**
-
-   .. ts:def:: PaymentStatus
-
-      interface PaymentStatus {
-
-        // Payment unique identifier
-        uuid: string;
-
-        // True for submitted payments
-        submitted: boolean;
-
-        // Creditor IBAN
-        creditorIban: string;
-
-        // Creditor BIC
-        creditorBic: string;
-
-        // Creditor legal name
-        creditorName: string;
-
-        // Amount
-        amount: string;
-
-        // Date of submission (in dashed form YYYY-MM-DD)
-        submissionDate: string;
-
-        // Date of preparation (in dashed form YYYY-MM-DD)
-        preparationDate: string;
-      }
-
-.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments
-  
-  Ask nexus to prepare instructions for a new payment.
-  Note that ``my-acct`` is the bank account that will be
-  **debited** after this operation.
-
-  **Request:**
-
-  .. ts:def:: PreparedPaymentRequest
-
-     interface PreparedPaymentRequest {
-       // IBAN that will receive the payment.
-       iban: string;
-       // BIC hosting the IBAN.
-       bic: string;
-       // Legal subject that will receive the payment.
-       name: string;
-       // payment subject. 
-       subject: string;
-       // amount, in the format CURRENCY:XX.YY
-       amount: string
-     }
-
-  **Response:**
-
-  .. ts:def:: PreparedPaymentResponse
-     
-     interface PreparedPaymentResponse {
-
-       // Opaque identifier to be communicated when
-       // the user wants to submit the payment to the
-       // bank.
-       uuid: string;
-     }
-
-.. http:post:: <nexus>/bank-accounts/<my-acct>/collected-transactions
-
-  Ask the default transport to download the latest transactions
-  related to ``my-acct`` and store them locally.
-
-  **Request:**
-
-  .. ts:def:: CollectedTransaction
-
-     interface CollectedTransaction {
-       // 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:get:: <nexus>/bank-accounts/<my-acct>/collected-transactions
-
-  Shows which transactions are stored locally at nexus.
-
-  **Query parameters:**
-
-  * **start** start (dashed YYYY-MM-DD) date of desired payments.
-    Optional, defaults to "earliest possible" date
-  * **end** end (dashed YYYY-MM-DD) date of desired payments.
-    Optional, defaults to "earliest possible" date
-
-
-  **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.