From 76472a9f2d6ede264ca5d3d5a97b7ab9ebec7085 Mon Sep 17 00:00:00 2001 From: ms Date: Fri, 17 Mar 2023 16:19:01 +0100 Subject: API Nexus. Matching specs and implementation, ~40%. --- libeufin/api-nexus.rst | 114 ++++++++++++++++++++++++------------------------- 1 file changed, 56 insertions(+), 58 deletions(-) (limited to 'libeufin/api-nexus.rst') 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. -- cgit v1.2.3