Rename to Circuit API.

1 files changed, 84 insertions, 79 deletions

diff --git a/libeufin/api-sandbox.rst b/libeufin/api-sandbox.rst
index 9a11217f..f4fbb3a2 100644
--- a/libeufin/api-sandbox.rst
+++ b/libeufin/api-sandbox.rst
@@ -20,32 +20,32 @@ only one demobank, named ``default``, is supported.  Such demobank
 activates the API segment ``/demobanks/default``, under which several
 APIs are then served.  The following sections describe all such APIs.
 
-Customer API
-^^^^^^^^^^^^
+Circuit API
+^^^^^^^^^^^
 
-This API offers CRUD operations on the bank's customers (or *users*)
-and sending funds between fixed bank accounts.  This last operation
-can be used to *cashout* LibEuFin assets to fiat currency.
+This API offers to manage a selected group of users who act as businesses 
+for a local currency.  Policies to disincentivize cashout operations may
+also apply, making therefore this setup a *circuit* within a wider traditional
+currency.
 
-For brevity, the list of response statuses for each endpoint may not
-always include all possible cases.
+For brevity, the list of response statuses for each endpoint may not be exhaustive.
 
 .. note::
    This API requires to **disable** ordinary registrations in the
    configuration, to avoid other APIs from circumventing this registration
    policy.  See ``libeufin-sandbox config --help``.
 
-The following endpoints are served under ``/demobanks/default/customer-api``.
+The following endpoints are served under ``/demobanks/default/circuit-api``.
 
-.. http:post:: /customers
+.. http:post:: /accounts
 
-   Create a new customer, including their bank account.  Only admin allowed.
+   Create a new bank account.  Only the administrator is allowed.
 
    **Request:**
 
-   .. ts:def:: CustomerRequest
+   .. ts:def:: CircuitAccountRequest
      
-     interface CustomerRequest {
+     interface CircuitAccountRequest {
        // Username
        username: string;
 
@@ -58,16 +58,16 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
        // Phone number.
        phone: string;
 
-       // Name denoting the legal subject being the customer.
+       // Legal subject owning the account.
        name: string;
 
        // 'payto' address pointing the bank account
-       // where to send payments, in case the customer
+       // where to send payments, in case the user
        // wants to convert the local currency back to
        // fiat.
        cashoutAddress: string;
 
-       // IBAN to assign to this bank account.  Randomly
+       // IBAN of this bank account.  Randomly
        // generated, when it is not given.
        iban?: string;
      }
@@ -75,51 +75,51 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
    **Response:**
 
    :http:statuscode:`204 No content`:
-     The customer was successfully created.
+     The account was successfully created.
    :http:statuscode:`409 Conflict`: 
-     One information was not available, the error message should inform
-     about it.
+     At least one registration detail was not available,
+     the error message should inform about it.
    :http:statuscode:`403 Forbidden`:
-     A istitutional username was attempted, like ``admin`` or ``bank``. 
+     The response should indicate one of the following reasons.     
+
+   * A istitutional username was attempted, like ``admin`` or ``bank``. 
+   * A non admin user tried the operation.
+
    :http:statuscode:`404 Bad request`:
      Input data was invalid.  For example, the client specified a invalid
-     phone number or e-mail.
+     phone number or e-mail address.
 
 
-.. http:delete:: /customers/$username
+.. http:delete:: /accounts/$username
   
-  Delete the customer with username ``$username``.  The deletion
-  succeeds only if the customer's balance is *zero*.  Only admin allowed.
+  Delete the account whose username is ``$username``.  The deletion
+  succeeds only if the balance is *zero*.  Only the administrator is
+  allowed.
 
   **Response:**
 
   :http:statuscode:`204 No content`:
-    The customer account was successfully deleted.
+    The account was successfully deleted.
   :http:statuscode:`404 Not found`:
-    The customer specified along the parameters was not found.
+    The username was not found.
   :http:statuscode:`403 Forbidden`:
     The administrator specified a istitutional username, like
     ``admin`` or ``bank``.
   :http:statuscode:`412 Precondition failed`:
-    The balance of the customer to delete was not zero.
+    The balance was not zero.
 
 .. _customer-password-modification:
 
-.. http:patch:: /customers
+.. http:patch:: /accounts/$username
 
-   Allows administrators *and* ordinary customers to
-   change the customer's password.
+   Allows administrators *and* ordinary users to
+   change the account's password.
 
    **Request:**
 
-   .. ts:def:: CustomerPasswordChange
+   .. ts:def:: AccountPasswordChange
       
-     interface Customer {
-       // Username of the customer whose password is
-       // to be changed.  It is optional in case the
-       // customer issues the request, because such information
-       // can be retrieved from the authentication credentials.
-       username?: string;
+     interface AccountPasswordChange {
 
        // New password.
        newPassword: string;
@@ -129,37 +129,31 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
 
    :http:statuscode:`204 No content`:
      Operation successful.
-   :http:statuscode:`403 Forbidden`:
-     A ordinary customer tried to change someone else's password.
-     This error should happen *before* checking whether the target
-     username exists, not to leak which usernames are already registered.
-   :http:statuscode:`404 Not found`:
-     The username whose password should be changed was not found.
 
-.. http:get:: /customers
+.. http:get:: /accounts
 
-   Obtains a list of all the customers registered at the bank.
-   It returns only the customer data (without any business information),
-   because :doc:`Access API </core/api-bank-access>` may already be used for that.
-   Only admin allowed.
+   Obtains a list of all the accounts registered at the bank.
+   It returns only the information that this API handles, without
+   any balance or transactions list.  The :doc:`Access API </core/api-bank-access>`
+   offers that.  This request is only available to the administrator.
 
    **Response:**
 
-   `Customers <customers-response_>`_
+   `CircuitAccounts <circuit-accounts_>`_
 
-   .. _customers-response:
+   .. _circuit-accounts:
 
-   .. ts:def:: Customers
+   .. ts:def:: CircuitAccounts
 
-     interfaces Customers {
-       customers: CustomerData[]; 
+     interfaces CircuitAccounts {
+       customers: CircuitAccountData[]; 
      }
 
-   .. _customer-data:
+   .. _circuit-account-data:
 
-   .. ts:def:: CustomerData
+   .. ts:def:: CircuitAccountData
      
-     interface CustomerData {
+     interface CircuitAccountData {
        // Username
        username: string;
 
@@ -172,28 +166,25 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
        // Phone number.
        phone: string;
 
-       // Name denoting the legal subject being the customer.
+       // Legal subject owning the account.
        name: string;
 
        // 'payto' address pointing the bank account
-       // where to send payments, in case the customer
-       // wants to convert the local currency back to
-       // fiat.
+       // where to send cashouts.
        cashoutAddress: string;
      }
 
 
-.. http:get:: /customers/$username
+.. http:get:: /accounts/$username
 
-   Obtains information relative to the customer with username ``$username``.
-   Admin and customer themselves allowed.
+   Obtains information relative to the account owned by
+   ``$username``.  The request is available to the administrator
+   and ``$username`` itself.
 
    **Response:**
 
-   `CustomerData <customer-data_>`_
+   `CircuitAccountData <circuit-account-data_>`_
 
-   :http:statuscode:`200 OK`:
-     Customer found and credentials correct.
    :http:statuscode:`403 Forbidden`:
      Unallowed user tried the operation.
 
@@ -203,7 +194,13 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
    is the one specified at registration time.  The account to be
    debited is extracted from the authentication credentials.
    The bank sends a TAN to the customer to let them confirm the
-   operation.  Only customers (= no admin) are allowed.
+   operation.  The request is only available to ordinary users, not
+   to the administrator.
+
+   .. note:
+     Fees likely apply to this operation, in order to incentivize
+     the circulation of the local currency.  Please refer to the bank's
+     terms and conditions. 
 
    **Request:**
 
@@ -226,9 +223,9 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
        amount: string; 
 
        // Which channel the TAN should be sent to.  If
-       // this field is missing, it defaults to SMS,
-       // since that is a different channel than the
-       // internet.
+       // this field is missing, it defaults to SMS.
+       // The default choice prefers to change the communication
+       // channel respect to the one used to issue this request.
        tanChannel?: TanChannel;
      }
 
@@ -238,7 +235,7 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
      
      interface CashoutPending {
        // UUID identifying the operation being created
-       // and now waiting the TAN confirmation.
+       // and now waiting for the TAN confirmation.
        uuid: string; 
      }
 
@@ -246,19 +243,22 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
      The cashout request was correctly created and
      the TAN authentication now is pending.
    :http:statuscode:`412 Precondition failed`:
-     Customer does not have sufficient funds.
+     The account does not have sufficient funds.
    :http:statuscode:`409 Conflict`:
      A istitutional user (``admin`` or ``bank``) tried the operation.
 
 .. http:post:: /cashouts/$cashoutId/abort
 
    Aborts the ``$cashoutId`` operation.  Original author
-   *and* admin are allowed.
+   *and* admin are both allowed.
 
    **Response:**
 
    :http:statuscode:`204 No content`:
-     cashout successfully aborted.
+     ``$cashoutId`` was found in the *pending* state
+     and got successfully aborted.
+   :http:statuscode:`412 Precondition failed`:
+     ``$cashoutId`` was already confirmed or aborted.
 
 .. http:post:: /cashouts/$cashoutId/refresh-tan
   
@@ -297,8 +297,13 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
    **Response:**
    
    :http:statuscode:`204 No content`:
-     cashout confirmed; also returned when using the same TAN
-     more than once.
+     ``$cashoutId`` was found in the *pending* state and
+     got successfully  confirmed.
+   :http:statuscode:`412 Precondition failed`:
+     ``$cashoutId`` was already confirmed or aborted.
+   ..
+     412 on a presumably pending operation is a proof
+     of a compromised TAN.
    :http:statuscode:`401 Unauthorized`:
      wrong TAN.
    :http:statuscode:`409 Conflict`:
@@ -307,7 +312,7 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
 .. http:get:: /cashouts/$cashoutId
 
    Informs about the status of the ``$cashoutId`` operation.
-   Original author and admin are allowed.
+   The request is available to the administrator and the original author.
 
    **Response:**
 
@@ -326,12 +331,12 @@ The following endpoints are served under ``/demobanks/default/customer-api``.
      
      enum CashoutStatus {
 
-       // The customer sent a valid TAN and the
-       // bank initiated the payment.
+       // The payment was initiated after a valid
+       // TAN was received by the bank.
        CONFIRMED = "confirmed",
 
        // The cashout was created and now waits
-       // the TAN by the customer.
+       // for the TAN by the author.
        PENDING = "pending",
 
        // The cashout was aborted before the