From 6dc6fb4fcba93f3bac3368ed0875205c043e3add Mon Sep 17 00:00:00 2001
From: Florian Dold <florian.dold@gmail.com>
Date: Wed, 24 Jun 2020 21:33:58 +0530
Subject: more docs

---
 libeufin/api-nexus.rst | 80 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 51 insertions(+), 29 deletions(-)

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 9c752de1..6424e73f 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -1,6 +1,8 @@
 Nexus API
 ###########
 
+.. contents:: Table of Contents
+
 HTTP API
 ========
 
@@ -13,8 +15,8 @@ basic auth* mechanism.
 Other authentication mechanisms (e.g. OpenID Connect) might
 be supported in the future.
 
-Users Management
-----------------
+User Management
+---------------
 
 .. http:get:: {nexusBase}/user
 
@@ -64,8 +66,11 @@ Users Management
 
   Return list of users.
 
-Bank Account Management
------------------------
+Bank Accounts
+-------------
+
+The LibEuFin maintains a copy of the bank account transaction history and balance information,
+manages payment initiations of the account and tracks the of payment initiations.
 
 .. http:get:: {nexusBase}/bank-accounts
   
@@ -301,17 +306,20 @@ to the real bank.
    List available bank connections.
 
 
-.. http:get:: {nexusBase}/bank-connections/{connid}
+.. http:get:: {nexusBase}/bank-connections/{connId}
 
    Get information about one bank connection.
 
    .. ts:def:: BankConnectionInfo
       
       interface BankConnectionInfo {
-         name: string;
+         bankConnectionId: string;
 
-         connectionType: string;
+         bankConnectionType: string;
 
+         // Is this bank connection ready, or
+         // are we waiting for the bank to activate
+         // the connection?
          ready: boolean;
 
          // Did the user review the bank's keys?
@@ -319,55 +327,69 @@ to the real bank.
       }
 
 
-.. http:post:: {nexusBase}/bank-connections/{connid}/connect
+.. http:post:: {nexusBase}/bank-connections/{connId}/connect
 
    Initialize the connection by talking to the bank.
 
-.. http:post:: {nexusBase}/bank-connections/{connid}/export-backup
+.. http:post:: {nexusBase}/bank-connections/{connId}/export-backup
 
    Make a passphrase-encrypted backup of this connection.
 
-.. http:post:: {nexusBase}/bank-connections/{connid}/accounts/fetch
+.. http:post:: {nexusBase}/bank-connections/{connId}/fetch-accounts
 
    Update accounts that are accessible via this bank connection.
 
-.. http:get:: {nexusBase}/bank-connections/{connid}/accounts
+.. http:get:: {nexusBase}/bank-connections/{connId}/accounts
 
-   List the bank accounts that are downloaded into this bank connection
-   but aren't imported yet:
+   List the bank accounts that this bank connection provides access to.
 
-  .. ts:def:: BankAccount
+  .. ts:def:: OfferedBankAccount
 
-     interface BankAccount {
-       
-       // iban
+     interface OfferedBankAccount {
+
+       // Unique identifier for the offered account
+       offeredAccountId: string;
+
+       // IBAN of the offered account
        iban: string;
 
-       // bic
+       // BIC of the account's financial institution
        bic: string;
 
-       // account holder
-       holder: string;
+       // Account owner name
+       ownerName: string;
 
-       // account label as given by the bank
+       // Account label as given by the bank
        account: string;
+
+       // If the accoun thas been imported,
+       // this field contains the ID of the
+       // Nexus bank account associated with it.
+       nexusBankAccountId: string | null;
      }
 
-.. http:post:: {nexusBase}/bank-connections/{connid}/accounts/import
+.. http:post:: {nexusBase}/bank-connections/{connId}/import-account
+
+  Import a bank account provided by the connection into the Nexus.
+
+  If no Nexus bank account with the ID ``nexusBankAccountId`` exists,
+  a new one will be created, and it will have ``connId`` as the
+  default bank connection.
 
-   Import one bank account, allowing the user to name it.
+  If an existing Nexus bank account with the same ID already exists,
+  this connection will be added as an available connection for it.
+  This only succeeds if the bank account has the same IBAN.
 
   .. ts:def:: ImportBankAccount
 
      interface ImportBankAccount {
 
-       // alphanumeric identifier given by the bank to
-       // the bank account to import.
-       accountId: string;
+       // Identifier for the bank account, as returned by /accounts
+       // of the bank connection.
+       offeredAccountId: string;
 
-       // alphanumeric name chosen by the user to identify
-       // locally such imported bank account.
-       localName: string;
+       // Nexus-local identifier for the bank account.
+       nexusBankAccountId: string;
      }
 
 Facades
-- 
cgit v1.2.3