From 2ec92c69c9f7c95b81561e87bfd943bc864aad5c Mon Sep 17 00:00:00 2001 From: MS Date: Sun, 11 Dec 2022 16:54:01 +0100 Subject: Rename to Circuit API. --- libeufin/api-sandbox.rst | 163 ++++++++++++++++++++++++----------------------- 1 file 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 ` 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 ` + offers that. This request is only available to the administrator. **Response:** - `Customers `_ + `CircuitAccounts `_ - .. _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 `_ + `CircuitAccountData `_ - :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 -- cgit v1.2.3