commit a94f8fd1040b9a23423553b57ced48c27d315095
parent 5f77ebbf4014afe65c54b3afc6dfe827ec70c487
Author: Sebastian <sebasjm@gmail.com>
Date: Mon, 23 Oct 2023 13:39:48 -0300
updated core bank spec
Diffstat:
| M | core/api-corebank.rst | | | 114 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------- |
1 file changed, 94 insertions(+), 20 deletions(-)
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -106,6 +106,9 @@ Config
}
+ :http:statuscode:`200 OK`:
+ Response is a `Config`.
+
Account Management
------------------
@@ -175,7 +178,7 @@ Account Management
**Response:**
- :http:statuscode:`204 No content`:
+ :http:statuscode:`201 Created`:
The account was successfully created.
:http:statuscode:`400 Bad request`:
Input data was invalid. For example, the client specified a invalid
@@ -268,13 +271,16 @@ Account Management
.. http:patch:: /accounts/$USERNAME/auth
Allows changing the account's password.
+
**Request:**
.. ts:def:: AccountPasswordChange
interface AccountPasswordChange {
-
+ // Old password. If present it need to match the current
+ // password before updating.
+ old_password?: string;
// New password.
new_password: string;
}
@@ -283,7 +289,13 @@ Account Management
:http:statuscode:`204 No content`:
Operation successful.
-
+ :http:statuscode:`404 Not found`:
+ The account pointed by ``$USERNAME`` was not found.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid credentials.
+ :http:statuscode:`403 Forbidden`:
+ The user is not allowed to change the ``$USERNAME`` password or
+ the "old_password" field in the request doesn't match the current pasword.
.. _account-list:
@@ -291,6 +303,14 @@ Account Management
Show those accounts whose histories are publicly visible. For example,
accounts from donation receivers. As such, this request is unauthenticated.
+
+
+ **Request:**
+
+ :query start: *Optional.*
+ Row identifier to explicitly set the *starting point* of the query.
+ :query delta: *Optional.*
+ The *delta* value that determines the range of the query.
**Response**
@@ -314,6 +334,10 @@ Account Management
account_name: string;
}
+ :http:statuscode:`200 OK`:
+ Response is a `PublicAccountsResponse`.
+ :http:statuscode:`204 No content`:
+ No public account.
.. http:get:: /accounts
@@ -383,6 +407,13 @@ Account Management
:http:statuscode:`200 OK`:
The bank responds with an `AccountData` object.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid credentials.
+ :http:statuscode:`403 Forbidden`:
+ Credentials are valid but this user has no permission to the
+ the account info.
+ :http:statuscode:`404 Not found`:
+ Username not found
**Details:**
@@ -442,7 +473,7 @@ Transactions
responds immediately, regardless of the result.
:query start: *Optional.*
Row identifier to explicitly set the *starting point* of the query.
- :query delta:
+ :query delta: *Optional.*
The *delta* value that determines the range of the query.
**Response**
@@ -453,6 +484,15 @@ Transactions
transactions: BankAccountTransactionInfo[];
}
+ :http:statuscode:`200 OK`:
+ The bank responds with an `BankAccountTransactionsResponse` object.
+ :http:statuscode:`204 No content`:
+ No transaction found.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid credentails
+ :http:statuscode:`404 Not found`:
+ Username not found
+
.. http:get:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions/${transaction_id}
**Response**
@@ -477,6 +517,13 @@ Transactions
date: Timestamp;
}
+ :http:statuscode:`200 OK`:
+ The bank responds with an `BankAccountTransactionInfo` object.
+ :http:statuscode:`404 Not found`:
+ Username not found
+ :http:statuscode:`401 Unauthorized`:
+ Invalid credentials.
+
.. http:post:: ${BANK_API_BASE_URL}/accounts/${account_name}/transactions
@@ -501,11 +548,12 @@ Transactions
**Response**
- :http:statuscode:`200 OK`:
- the transaction has been created.
-
- :http:statuscode:`400 Bad Request`:
- the request was invalid or the payto://-URI used unacceptable features.
+ :http:statuscode:`204 No content`:
+ the transaction has been created.
+ :http:statuscode:`400 Bad Request`:
+ the request was invalid or the payto://-URI used unacceptable features.
+ :http:statuscode:`401 Unauthorized`:
+ Invalid credentials.
Taler Withdrawals
@@ -536,8 +584,10 @@ Taler Withdrawals
// URI that can be passed to the wallet to initiate the withdrawal.
taler_withdraw_uri: string;
- }
+ }
+ :http:statuscode:`200 Ok`:
+ The bank responds with an `BankAccountCreateWithdrawalResponse` object.
:http:statuscode:`403 Forbidden`:
The operation was rejected due to insufficient funds.
@@ -577,6 +627,10 @@ Taler Withdrawals
selected_exchange_account: string | null;
}
+ :http:statuscode:`200 Ok`:
+ The bank responds with an `BankAccountGetWithdrawalResponse` object.
+ :http:statuscode:`404 Not found`:
+ The operation was not found.
.. http:post:: ${BANK_API_BASE_URL}/withdrawals/${withdrawal_id}/abort
@@ -584,7 +638,7 @@ Taler Withdrawals
withdrawal operation. Does not require further authentication as knowledge
of the withdrawal ID serves as an authenticator.
- :http:statuscode:`200 OK`: The withdrawal operation has been aborted. The response is an empty JSON object.
+ :http:statuscode:`204 No content`: The withdrawal operation has been aborted. The response is an empty JSON object.
:http:statuscode:`409 Conflict`: The reserve operation has been confirmed previously and can't be aborted.
@@ -597,7 +651,7 @@ Taler Withdrawals
**Response**
- :http:statuscode:`200 OK`:
+ :http:statuscode:`204 No content`:
The withdrawal operation has been confirmed. The response is an empty JSON object.
:http:statuscode:`409 Conflict`:
The withdrawal has been aborted previously and can't be confirmed.
@@ -643,6 +697,11 @@ Cashouts
**Request:**
+ :query start: *Optional.*
+ Row identifier to explicitly set the *starting point* of the query.
+ :query delta: *Optional.*
+ The *delta* value that determines the range of the query.
+
`CashoutRequest <cashout-request_>`_
.. ts:def:: TanChannel
@@ -700,6 +759,8 @@ Cashouts
exchange rate was calculated incorrectly by the client.
:http:statuscode:`503 Service unavailable`:
The bank does not support the TAN channel for this operation.
+ The bank does not support cashout, client should check config response.
+
**Details:**
@@ -728,6 +789,8 @@ Cashouts
also when ``$CASHOUT_ID`` got aborted before this request.
:http:statuscode:`409 Conflict`:
``$CASHOUT_ID`` was already confirmed.
+ :http:statuscode:`503 Service unavailable`:
+ This server does not support cashout, client should check config response.
.. _cashout-confirm:
@@ -759,7 +822,8 @@ Cashouts
also when ``$CASHOUT_ID`` got aborted before this request.
:http:statuscode:`409 Conflict`:
The user changed their cash-out address between the creation and the confirmation of ``$CASHOUT_ID``.
-
+ :http:statuscode:`503 Service unavailable`:
+ This server does not support cashout, client should check config response.
.. _cashout-rates:
@@ -806,6 +870,8 @@ Cashouts
supported. The response should clarify which case.
:http:statuscode:`404 Not found`:
The server does not support local currency conversion.
+ :http:statuscode:`503 Service unavailable`:
+ This server does not support cashout, client should check config response.
.. _circuit-cashouts:
@@ -832,10 +898,13 @@ Cashouts
}
:http:statuscode:`200 OK`:
- At least one cash-out operation was found.
-
+ Response is a `Cashouts`.
:http:statuscode:`204 No Content`:
No cash-out operations were found at the bank
+ :http:statuscode:`404 Not found`:
+ Username not fuond.
+ :http:statuscode:`503 Service unavailable`:
+ This server does not support cashout, client should check config response.
.. http:get:: /cashouts
@@ -867,10 +936,11 @@ Cashouts
}
:http:statuscode:`200 OK`:
- At least one cash-out operation was found.
-
+ Response is a `GlobalCashouts`.
:http:statuscode:`204 No Content`:
No cash-out operations were found at the bank
+ :http:statuscode:`503 Service unavailable`:
+ This server does not support cashout, client should check config response.
.. _circuit-cashout-details:
@@ -914,9 +984,13 @@ Cashouts
**Response:**
+ :http:statuscode:`200 OK`:
+ Response is a `CashoutStatusResponse`.
:http:statuscode:`404 Not found`:
The cashout operation was not found.
Aborted cashout operations will also not be found.
+ :http:statuscode:`503 Service unavailable`:
+ This server does not support cashout, client should check config response.
Monitor
@@ -957,12 +1031,12 @@ Monitor
:http:statuscode:`200 OK`:
The bank responds with `MonitorResponse`.
- :http:statuscode:`404 Not Found`:
- The bank doesn't have the conversion service.
-
:http:statuscode:`400 Bad Request`:
This error may indicate that the *which* parameter is not appropriate for the selected *timeframe*. For example, timeframe=month and which=20 would result in this error.
+ :http:statuscode:`503 Service unavailable`:
+ The bank doesn't have the conversion service.
+
.. note::
API consumers may combine the values in the response with other
