API Nexus.

Matching specs and implementation, ~40%.

1 files changed, 56 insertions, 58 deletions

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index d88bbc70..0e08d1d1 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -8,26 +8,15 @@ Nexus API
 HTTP API
 ========
 
+In the current version, the API calls are only available to
+the superuser, when no authorization condition is explictly stated.
+
 Configuration
 -------------
 
-Returns configuration values currently used by the Nexus process.
-This API is mostly used by testing jobs.
-
-.. http:get:: {nexusBase}/service-config
-
-  **Response:**
-
-  .. ts:def:: ServiceConfigResponse
-
-     interface ConfigResponse {
-
-       // Connection string to the database.
-       dbConn: string;
-     }
-
 
 Returns configuration values currently used by Nexus.
+This call is unauthenticated.
 
 .. http:get:: {nexusBase}/config
 
@@ -37,8 +26,6 @@ Returns configuration values currently used by Nexus.
 
      interface ConfigResponse {
 
-       currency: string;
-
        // nexus version, X.Y.Z format.
        version: string;
      }
@@ -58,8 +45,8 @@ User Management
 
 .. http:get:: {nexusBase}/user
 
-  Get information about the current user (based on the authentication information
-  in this request).
+  Get information about the current user.  The username carried
+  along the HTTP basic auth points at the user to be shown.
 
   **Response:**
 
@@ -70,14 +57,14 @@ User Management
        // User name
        username: string;
 
-       // Password
-       password: string;
+       // Is this a super user?
+       superuser: Boolean;
      }
 
-.. http:post:: {nexusBase}/users/password
+.. http:post:: {nexusBase}/users/{userName}/password
 
-  Change password of a user.  The username is extracted from
-  the HTTP authentication parameters.
+  Change password of the ``{userName}`` user.  The call is
+  available to any superuser on any username.
 
   **Request:**
 
@@ -87,6 +74,11 @@ User Management
       newPassword: string;
     }
 
+  **Response:**
+
+  :http:statuscode:`200 OK`: The password was successfully changeD.
+
+
 .. http:post:: {nexusBase}/users
 
   Create a new user.  Only a superuser can call this API.
@@ -115,21 +107,29 @@ User Management
 
 .. http:get:: {nexusBase}/users
 
-  Return list of users.
+  Return the list of all users.
+
+  **Response:**
+
+  .. ts:def:: UsersResponse
+
+     interface UsersResponse {
+       users: UserResponse[];
+     }
 
 .. _nexus-permissions-api:
 
 Permissions API
 ---------------
 
-The permissions API manages authorization of access of subjects (usually users)
-to resources.
+The permissions API manages authorization of access of subjects
+(usually users) to resources.
 
-Permissions are modeled a set of ``(subject, resource, permission)`` triples.
-Subjects and resources consist of a type and an identifier.
+Permissions are modeled a set of ``(subject, resource, permission)``
+triples.  Subjects and resources consist of a type and an identifier.
 
-Superusers are not subject to further permission checks, they are allowed
-to do any operation.
+Superusers are not subject to further permission checks, they are
+allowed to do any operation.
 
 The following subject types are currently supported:
 
@@ -140,17 +140,17 @@ The following permissions are currently defined:
 
 * ``facade.talerWireGateway.history``:  Allows querying the
   transaction history through a Taler wire gateway facade.
-* ``facade.talerWireGateway.transfer``: Allows creating payment initiations
-  to transfer money via a Taler wire gateway facade.
+* ``facade.talerWireGateway.transfer``: Allows creating payment
+  initiations to transfer money via a Taler wire gateway facade.
 
 The following resource IDs are currently supported:
 
-* ``facade``: A LibEuFin facade.  The resource ID is interpreted as the
-  facade name.
+* ``facade``: A LibEuFin facade.  The resource ID is interpreted
+  as the facade name.
 
 .. http:get:: {nexusbase}/permissions
 
-   List all permissions.
+   Lists all permissions.
 
    **Response**
 
@@ -168,7 +168,7 @@ The following resource IDs are currently supported:
 
 .. http:post:: {nexusbase}/permissions
 
-   Modify permissions.
+   Modifies permissions.
 
    **Request**
 
@@ -193,7 +193,6 @@ The following resource IDs are currently supported:
 Test API
 --------
 
-
 .. http:post:: {nexusbase}/bank-accounts/{acctid}/test-camt-ingestion/{type}
 
   This call allows tests to **directly** give Nexus a Camt document.  After
@@ -210,15 +209,16 @@ Test API
 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 initiations of payments.
+Neuxs maintains a copy of the bank account transaction history and
+balance information, manages payment initiations of the account and
+tracks the initiations of payments.
 
 .. http:get:: {nexusBase}/bank-accounts
 
   **Response:**
 
-  A list of `BankAccount` objects
-  that belong to the requester.
+  A list of `BankAccount` objects that belong to the requester.
+  The list is held in the ``accounts`` field.
 
   .. ts:def:: BankAccount
 
@@ -254,7 +254,7 @@ manages payment initiations of the account and tracks the initiations of payment
 
 .. http:post:: {nexusBase}/bank-accounts/{acctid}/payment-initiations/{pmtid}/submit
 
-  Ask nexus to submit one prepare payment at the bank.
+  Asks nexus to submit one prepare payment at the bank.
 
   :http:statuscode:`404 Not found`: the unique identifier **or**
   the bank connection could not be found in the system
@@ -262,7 +262,7 @@ manages payment initiations of the account and tracks the initiations of payment
 
 .. http:get:: {nexus}/bank-accounts/{my-acct}/payment-initiations/{uuid}
 
-   Ask the status of payment ``$uuid``.
+   Asks the status of payment ``$uuid``.
 
    **Response:**
 
@@ -302,7 +302,7 @@ manages payment initiations of the account and tracks the initiations of payment
 
 .. http:get:: {nexusBase}/bank-accounts/{my-acct}/payment-initiations
 
-  Ask nexus the list of initiated payments.  At this stage of the API,
+  Asks nexus the list of initiated payments.  At this stage of the API,
   **all** is returned: submitted and non-submitted payments.
 
   **Response**
@@ -362,7 +362,7 @@ manages payment initiations of the account and tracks the initiations of payment
      interface CollectedTransaction {
 
          // This type indicates the time range of the query.
-         // It can assume the following values:
+         // It allows the following values:
          //
          // 'latest': retrieves the last transactions from the bank.
          //           If there are older unread transactions, those will *not*
@@ -385,13 +385,13 @@ manages payment initiations of the account and tracks the initiations of payment
          // lets the request specify which type of batch ought to be
          // returned.  Currently, the following two type are supported:
          //
-         // 'report': intra-day information
-         // 'statement': prior day bank statement
+         // 'report': typically includes only non booked transactions.
+         // 'statement': typically includes only booked transactions.
          level: string;
 
-         // Bank connection to use.  It is a *optional* value that
-         // defaults to the default bank connection, if not given.
-         bankConnection: string;
+         // Bank connection to use.  Uses the default bank connection,
+         // when not given.
+         bankConnection: string?;
      }
 
   **Response:**
@@ -407,17 +407,15 @@ manages payment initiations of the account and tracks the initiations of payment
       downloadedTransactions: number;
     }
 
-.. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions
+  :http:statuscode:`500 Internal Server Error`: Nexus itself had a problem
+  along the operation, and not the bank.
 
-  Shows which transactions are stored locally at nexus.
 
-  **Query parameters:**
+.. http:get:: {nexusBase}/bank-accounts/{acctid}/transactions
 
-  * **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.
+  Shows all the transactions fetched for ``{acctid}``.
 
+  **Query parameters:**
 
   **Response:** A object with a unique field named ``transactions``
   that contains a list of `Transaction` objects.