1 files changed, 300 insertions, 0 deletions
diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst
new file mode 100644
index 00000000..2cd0b2eb
--- /dev/null
+++ b/libeufin/api-nexus2.rst
@@ -0,0 +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
+----------------
+
+.. 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;
+
+       // Optional field to 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 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:**
+
+  .. 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:: 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: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.