From a073c127d324bb0667bacff1f94499340c3f6385 Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Tue, 19 May 2020 18:24:46 +0530 Subject: libeufin docs --- libeufin/api-nexus.rst | 111 +++++++++++++++++++++++-------------------------- libeufin/concepts.rst | 56 ++++++++++++------------- 2 files changed, 79 insertions(+), 88 deletions(-) (limited to 'libeufin') diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst index 681811aa..f175c9d9 100644 --- a/libeufin/api-nexus.rst +++ b/libeufin/api-nexus.rst @@ -36,7 +36,7 @@ Users Management .. http:post:: /users - Create a new user. Only the super-user can call this API. + Create a new user. Only a superuser can call this API. **Request:** @@ -59,6 +59,11 @@ Users Management password: string; } + +.. http:get:: /users + + Return list of users. + Bank Account Management ----------------------- @@ -95,27 +100,13 @@ Bank Account Management // to submit at the bank. uuid: string; - // Specify the bank transport to use for the submission. - transport?: Transport; + // Specify the bank connectionto use for the submission. + connection?: string; } - .. ts:def:: Transport - - interface Transport { - - // Transport type: 'ebics', 'local', 'fints' (forthcoming). - // It must match one of the types actually implemented by - // nexus. - type: string; - - // A mnemonic identifier given by the user to one particular - // transport instance. - name: string; - } - :status 404 Not Found: the unique identifier **or** - the bank transport could not be found in the system + the bank connection could not be found in the system .. http:get:: /bank-accounts//prepared-payments/$uuid @@ -193,16 +184,16 @@ Bank Account Management .. http:post:: /bank-accounts/collected-transactions - Nexus will download bank transactions from the given transport. + Nexus will download bank transactions using the given connection. **Request:** .. ts:def:: CollectedTransaction interface CollectedTransaction { - // Optional field to specify the bank transport to + // Optional field to specify the bank connection to // use for such operation. - bankTransport?: Transport; + bankConnection: connection; // dashed date (YYYY-MM-DD) of the earliest payment // in the result. Optional, defaults to "earliest // possible" date. @@ -254,57 +245,58 @@ Bank Account Management subject: string; } -Bank Transports + +Bank Connections --------------- -Bank transports connect the local LibEuFin bank account +Bank connections connect the local LibEuFin bank account to the real bank. -.. http:post:: /bank-transports +.. http:post:: /bank-connections - Activate a new bank transport for the requesting user. + Activate a new bank connection for the requesting user. **Request:** - .. ts:def:: BankTransport + .. ts:def:: BankConnectionRestoreRequest - interface BankTransport { + interface BankConnectionRestoreRequest { - transport: Transport; + name: string; - // Restore a previous transport. Take precedence + // Restore a previous connection. Take precedence // over the 'new' field. - backup?: TransportBackup; + backup?: BankConnectionBackup; - // Data to create a fresh bank transport without + // Data to create a fresh bank connection without // restoring any backup. - data?: TransportNew; + data?: BankConnectionNew; } - .. ts:def:: TransportNew + .. ts:def:: ConnectionNew - interface TransportNew { + interface ConnectionNew { // This type is strictly dependent on - // the transport being created. For Ebics, + // the connection being created. For Ebics, // it will contain the required fields (as strings): // 'ebicsURL', 'userID', 'partnerID', 'hostID', and // the optional 'systemID'. - // Other transport types, like 'local' (used for testing + // Other connection types, like 'local' (used for testing // purposes skipping any interaction with the bank service) // and 'fints' are all work in progress! } - .. ts:def:: TransportBackup + .. ts:def:: BankConnectionBackup - interface TransportBackup { + interface BankConnectionBackup { // The information needed in this type depend entirely - // on which transport is being restored. + // on which connectionis being restored. } @@ -313,30 +305,29 @@ to the real bank. :status 409 Conflict: The ``name`` field exists already for the requesting user. -.. http:post:: /bank-transports/sendMSG. - - Perform the ``MSG`` operation offered by ``transport-name`` - **without** affecting the nexus database. - **Request:** - - A `Transport` object. +.. http:post:: /bank-connections - **Response:** + List available bank connections. - :status 404 Not Found: ``transport-name`` doesn't exist for - the requesting user. -.. http:post:: /bank-transports//syncMSG. - - Some transports **do** have operations that aren't semantically - related to a bank account but need to be stored locally at the nexus. - One typical example is the downloading of the bank's keys vie the - EBICS transport. This API lets the user perform the ``MSG`` - operation that should result in new data being stored locally - at the nexus. +EBICS-specific APIs +------------------- - **Response:** +The following endpoints are only available for EBICS bank connections. +They are namespaced under the ``/ebics/`` sub-resource. - :status 404 Not Found: ``transport-name`` doesn't exist for - the requesting user. +.. http:post:: /bank-connections//ebics/download/ + + + Perform an EBICS download transaction of type ``msg``. + This request will not affect any bank account or other state + in the nexus database. It will just make a request to the bank + and return the answer. + +.. http:post:: /bank-connections//ebics/upload/ + + Perform an EBICS upload transaction of type ``msg``. + This request will not affect any bank account or other state + in the nexus database. It will just make a request to the bank + and return the answer. diff --git a/libeufin/concepts.rst b/libeufin/concepts.rst index 00afe9a6..da48d7f8 100644 --- a/libeufin/concepts.rst +++ b/libeufin/concepts.rst @@ -57,42 +57,42 @@ The information stored about it includes: with their state (sent or not sent, acknowledged in bank statement or not). * Error reports (e.g. failed payment requests, bank statement items that were not understood by LibEuFin) -* A default bank transport (if configured) that is used by default +* A default bank connection (if configured) that is used by default for operations on the account -* Other connected bank transports +* Other enabled bank connections Examples: .. code:: none - # Download latest transactions via the default bank transport and store them locally + # Download latest transactions via the default bank connection and store them locally curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-accounts/my-acct/collect-transactions -Bank Transports ---------------- +Bank Connections +---------------- -Bank transports connect the local LibEuFin bank account to the real bank. -The bank transport includes the following data: +Bank connections connect the local LibEuFin bank account to the real bank. +The bank connection includes the following data: -* Local alias ("nickname") of the bank transport -* the type of transport (EBICS, FinTS, loopback, sandbox) -* credentials to use the transport (e.g. password, EBICS subscriber keys) +* Local alias ("nickname") of the bank connection +* the type of connection, i.e. the protocol used (EBICS, FinTS, loopback, sandbox) * protocol configuration (hostname, port, protocol sub-version/flags) +* credentials to use the connection (e.g. password, EBICS subscriber keys) -Bank transports provide the following actions: +Bank connections provide the following actions: -* Initial setup of the transport +* Initial setup of the connection * Execute protocol-specific actions (e.g. EBICS: C53, C52, CCT, CRZ) * These actions do not have any effect on the LibEuFin local bank account. To persist changes to the local bank account (transaction history, payment request status), - the bank transport must be invoked via the bank account. + the bank connection must be invoked via the bank account. * Import bank accounts - * Some bank transport protocols allow LibEuFin to query a list of bank - accounts that the transport has access to. This makes setup easier, + * Some bank connection protocols allow LibEuFin to query a list of bank + accounts that the connection has access to. This makes setup easier, as the user doesn't have to create the local bank account manually. Examples: @@ -100,22 +100,22 @@ Examples: .. code:: none # Manually request the inter-day account report via the EBICS C52 order - curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-transports/my-ebics-testacct/send-c52 + curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connections/my-ebics-testacct/send-c52 - # Download available bank accounts that can be accessed through this transport, + # Download available bank accounts that can be accessed through this connection, # according to the bank server (with EBICS, does a HTD request). # For each of them, create a bank account resource in LibEuFin. - curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-transports/my-ebics-testacct/import-accounts + curl -XPOST $AUTHEADER https://example1.libeufin.tech/bank-connection/my-ebics-testacct/import-accounts Facades ------- Facades allow extra domain-specific functionality to be implemented on top of users, bank accounts -and bank transports. Facades store the following information: +and bank connections. Facades store the following information: * Local name of the facade * Facade type and options specific to the type -* Associated bank accounts and bank transports that can be accessed by the layer +* Associated bank accounts and bank connections that can be accessed by the layer * Internal tables used by the facade (i.e. facades are stateful) The only facade currently supported by LibEuFin is the "Taler Wire Gateway API" layer. @@ -135,7 +135,7 @@ Access Control The goal of access control in LibEuFin is to allow the following scenarios: -* The Nexus can be used by multiple clients for different bank accounts/transports, +* The Nexus can be used by multiple clients for different bank accounts/connections and these users can't access each other's bank accounts * For monitoring / dashboard (e.g. Taler rejected transactions, blacklists), some users should only be able to have read-only access. @@ -146,15 +146,15 @@ spending limits or more fine-grained read/write permissions. Users can be normal users or superusers. Permission checks do not apply to superusers, and only superusers can create other users. -Each top-level object (bank account, bank transport, layer) has a list of +Each top-level object (bank account, bank connection, facade) has a list of nexus users with write access, and a list of users with read access. -When using a bank transport through a bank account, permission checks must -succeed for both the bank account and the bank transport. +When using a bank connection through a bank account, permission checks must +succeed for both the bank account and the bank connection -This works differently for layers: A layer has a set of associated bank transports +This works differently for facades: A facade has a set of associated bank connections and bank accounts it can access. Permissions on these associated objects -are checked when the layer is *created*. When invoking operations on the layer, -the nexus only checks if the current nexus user can access the layer and *not* the -underlying objects abstracted by the layer. +are checked when the facade is *created*. When invoking operations on the facade, +the nexus only checks if the current nexus user can access the facade and *not* the +underlying objects abstracted by the facade. -- cgit v1.2.3