[taler-docs] branch master updated (864be01 -> 705f17a)

[gnunet]

This is an automated email from the git hooks/post-receive script.

ms pushed a change to branch master
in repository docs.

    from 864be01  Merge branch 'master' of git+ssh://git.taler.net/docs
     new 4f54120  use optional type notation
     new 76013b8  fix optional field notation
     new c77c686  fix plural
     new 5f538d1  rename file
     new b79d140  add missing fields
     new 705f17a  missing field

The 6 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 libeufin/api-nexus.rst  | 334 +++++++++++++++++++++++++++++++++---------------
 libeufin/api-nexus2.rst | 300 -------------------------------------------
 libeufin/index.rst      |   2 +-
 3 files changed, 229 insertions(+), 407 deletions(-)
 delete mode 100644 libeufin/api-nexus2.rst

diff --git a/libeufin/api-nexus.rst b/libeufin/api-nexus.rst
index 745182c..699fdaf 100644
--- a/libeufin/api-nexus.rst
+++ b/libeufin/api-nexus.rst
@@ -1,187 +1,309 @@
 Nexus API
 ###########
 
-
 HTTP API
 ========
 
+Authentication
+--------------
+
+Currently every request made to nexus must be authenticated using the *HTTP
+basic auth* mechanism.
+
+Other authentication mechanisms (e.g. OpenID Connect) might
+be supported in the future.
+
 Users Management
 ----------------
 
-Users are the entity that access accounts.  They do not necessarily correspond
-to the actual legal owner of an account.  Their main purpose in the nexus is
-access management.
+.. http:get:: <nexus>/user
 
-.. http:get:: <nexus>/users
+  Get information about the current user (based on the authentication 
information
+  in this request).
 
-  List users.
+  **Response:**
 
-  **Required permission:** Administrator.
+  .. ts:def:: GetUserResponse
+
+     interface UserResponse {
+
+       // User name
+       username: string;
+
+       // Is it a superuser?
+       superuser: boolean;
+     }
 
 .. http:post:: <nexus>/users
 
-  Create a new user.
+  Create a new user.  Only the super-user can call this API.
+
+  **Request:**
 
-  **Required permission:** Administrators.
+  The body is a `User` object.
 
+  **Response:**
+
+  :status 409 Conflict: Username is not available.
+
+  **Details:**
+
+  .. ts:def:: CreateUserRequest
+
+     interface User {
+
+       // User name
+       username: string;
+
+       // Initial password
+       password: string;
+     }
 
 Bank Account Management
 -----------------------
 
 .. http:get:: <nexus>/bank-accounts
+  
+  **Response:**
 
-  List bank accouts managed by nexus.
+  A list of `BankAccount` objects
+  that belong to the requester.
 
+  .. ts:def:: BankAccount
+     
+     interface BankAccount {
+       // mnemonic name identifying this bank account.
+       account: string; 
+       // IBAN
+       iban: string;
+       // BIC
+       bic: string;
+       // Legal subject owning the account.
+       holder: string;
+     }
 
-.. http:post:: <nexus>/bank-accounts
+.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments/submit
 
-  List bank accouts managed by nexus.
+  Ask nexus to submit one prepare payment at the bank.
 
+  **Request:**
 
-.. http:get:: <nexus>/bank-accounts/{acctid}/history
+  .. ts:def:: SubmitPayment
 
-  :query method: Method to query the bank transaction (cached, ebics, fints, 
...)
+     interface SubmitPayment {
+       // Unique identifier of the (previously) prepared payment
+       // to submit at the bank.
+       uuid: string;
 
-  Query the transaction history of an account via the specified method.
+       // Specify the bank transport to use for the submission.
+       transport?: string;
+     }
 
+  :status 404 Not Found: the unique identifier **or**
+    the bank transport could not be found in the system
 
-.. http:get:: <nexus>/bank-accounts/{acctid}/payments
 
-  List payments made with this bank account via nexus.
+.. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payments/$uuid
+   
+   Ask the status of payment ``$uuid``.
 
-.. http:post:: <nexus>/bank-accounts/{acctid}/payments
+   **Response:**
 
-  Initiate a payment.
+   .. ts:def:: PaymentStatus
 
+      interface PaymentStatus {
 
-Low-level EBICS API
--------------------
+        // Payment unique identifier
+        uuid: string;
 
-.. http:post:: <nexus>/ebics/subscribers/{id}/backup
-  
-  Ask the server to export the three keys, protected with passphrase.
+        // True for submitted payments
+        submitted: boolean;
 
-  .. ts:def:: NexusEbicsBackupRequest
-    
-    interface NexusEbicsBackupRequest {
-      passphrase: string;
-    }
+        // Creditor IBAN
+        creditorIban: string;
 
+        // Creditor BIC
+        creditorBic: string;
 
-  .. ts:def:: NexusEbicsBackupResponse
+        // Creditor legal name
+        creditorName: string;
 
-    interface NexusEbicsBackupResponse {
-      
-      // The three passphrase-protected private keys in the PKCS#8 format
+        // Amount
+        amount: string;
 
-      authBlob: string; // base64
-      encBlob: string; // base64
-      sigBlob: string; // base64
-      hostID: string;
-      userID: string;
-      partnerID: string;
-      ebicsURL: string;
-    }
+        // Subject
+        subject: string;
 
+        // Date of submission (in dashed form YYYY-MM-DD)
+        submissionDate: string;
 
-.. http:post:: <nexus>/ebics/subscribers/{id}/restoreBackup
+        // Date of preparation (in dashed form YYYY-MM-DD)
+        preparationDate: string;
+      }
+
+.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments
   
-  Ask the server to restore the keys.  Always creates a NEW
-  "{id}" account, and fails if it exists already.
+  Ask nexus to prepare instructions for a new payment.
+  Note that ``my-acct`` is the bank account that will be
+  **debited** after this operation.
+
+  **Request:**
+
+  .. ts:def:: PreparedPaymentRequest
+
+     interface PreparedPaymentRequest {
+       // IBAN that will receive the payment.
+       iban: string;
+       // BIC hosting the IBAN.
+       bic: string;
+       // Legal subject that will receive the payment.
+       name: string;
+       // payment subject. 
+       subject: string;
+       // amount, in the format CURRENCY:XX.YY
+       amount: string
+     }
+
+  **Response:**
+
+  .. ts:def:: PreparedPaymentResponse
+     
+     interface PreparedPaymentResponse {
+
+       // Opaque identifier to be communicated when
+       // the user wants to submit the payment to the
+       // bank.
+       uuid: string;
+     }
+
+.. http:post:: <nexus>/bank-accounts/<my-acct>/collected-transactions
 
-  .. ts:def:: NexusEbicsRestoreBackupRequest
+  Ask the default transport to download the latest transactions
+  related to ``my-acct`` and store them locally.
 
-    interface NexusEbicsRestoreBackupRequest {
-      
-      // passphrase to decrypt the keys
-      passphrase: string;
+  **Request:**
 
-      // The three passphrase-protected private keys in the PKCS#8 format
-      authBlob: string; // base64
-      encBlob: string; // base64
-      sigBlob: string; // base64
-      hostID: string;
-      userID: string;
-      partnerID: string;
-      ebicsURL: string;
-    }
+  .. ts:def:: CollectedTransaction
 
-  .. ts:def:: NexusEbicsCreateSubscriber
+     interface CollectedTransaction {
+       // Optional field to specify the bank transport to
+       // use for such operation.
+       bankTransport?: string;
+       // dashed date (YYYY-MM-DD) of the earliest payment
+       // in the result. Optional, defaults to "earliest
+       // possible" date.
+       start: string;
+       // dashed date (YYYY-MM-DD) of the earliest payment
+       // in the result. Optional, defaults to "latest
+       // possible" date.
+       end: string;
+     }
 
-.. http:post:: <nexus>/ebics/subscribers
+.. http:get:: <nexus>/bank-accounts/<my-acct>/collected-transactions
 
-  Create a new subscriber.  Create keys for the subscriber that
-  will be used in later operations.
+  Shows which transactions are stored locally at nexus.
 
-  .. ts:def:: NexusEbicsCreateSubscriber
+  **Query parameters:**
 
-    interface NexusEbicsCreateSubscriber {
-      ebicsUrl: string;
-      hostID: string;
-      partnerID: string;
-      userID: string;
-      systemID: string?
-    }
+  * **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
 
 
-.. http:get:: <nexus>/ebics/subscribers
+  **Response:** A list of `Transaction` objects.
 
-  List EBICS subscribers managed by nexus.
+  .. ts:def:: Transaction
 
+     interface Transaction {
+       // local bank account involved in the transaction.
+       account: string;
 
-.. http:get:: <nexus>/ebics/subscribers/{id}
+       // counterpart IBAN
+       counterpartIban: string;
 
-  Get details about an EBICS subscriber.
+       // counterpart BIC
+       counterpartBic: string;
 
-.. http:get:: <nexus>/ebics/subscriber/{id}/keyletter
+       // counterpart holder name
+       counterpartName: string;
 
-  Get a formatted letter (mark-down) to confirm keys via ordinary mail.
+       // amount, in the format [-]CURRENCY:XX.YY,
+       // where the minus sign as prefix indicates
+       // a debit for the user's bank account.
+       amount: string;
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sendIni
+       // Dashed date YYYY-MM(01-12)-DD(01-31) of the transaction.
+       date: string;
 
-  Send INI message to the EBICS host.
+       // Payment subject.
+       subject: string;
+     }
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sendHia
+Bank Transports
+---------------
 
-  Send HIA message to the EBICS host.
+Bank transports connect the local LibEuFin bank account
+to the real bank.
 
-.. http:get:: <nexus>/ebics/subscriber/{id}/sendHtd
+.. http:post:: <nexus>/bank-transports
+  
+  Activate a new bank transport for the requesting user.
+
+  **Request:**
+  Object of the type `BankTransport`
+
+  **Response:**
+
+  :status 409 Conflict: The ``name`` field exists already for
+    the requesting user.
 
-  Send HTD message to the EBICS host.
+  **Details:**
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sync
+  .. ts:def:: BankTransport
 
-  Synchronize with the EBICS server.  Sends the HPB message
-  and updates the bank's keys.
+     interface BankTransport {
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/sendEbicsOrder
+       // Mnemonic identifier for the transport bein created.
+       name: string;
 
-  Sends an arbitrary bank-technical EBICS order.  Can be an upload
-  order or a download order.
+       // Optional field to restore a previous transport.
+       backup: TransportBackup;
 
-  .. ts:def:: NexusEbicsSendOrderRequest::
+       // Type of the transport (ebics, fints, native, ..)
+       type: string;
+     }
 
-    interface NexusEbicsSendOrderRequest {
-      // Bank-technical order type, such as C54 (query transactions)
-      // or CCC (initiate payment)
-      orderType: string;
 
-      // Generic order parameters, such as a date range for querying
-      // an account's transaction history.
-      orderParams: OrderParams
+  .. ts:def:: TransportBackup
+     
+     interface TransportBackup {
 
-      // Body (XML, MT940 or whatever the bank server wants)
-      // of the order type, if it is an upload order
-      orderMessage: string;
-    }
+      // The information needed in this type depend entirely
+      // on which transport is being restored.
 
+     }
 
-.. http:post:: <nexus>/ebics/subscriber/{id}/ebicsOrders
+.. http:post:: <nexus>/bank-transports/<transport-name>/sendMSG.
+  
+  Perform the ``MSG`` operation offered by ``transport-name``
+  **without** affecting the nexus database.
+
+  **Response:**
 
-  .. note::
+  :status 404 Not Found: ``transport-name`` doesn't exist for
+    the requesting user.
+
+.. http:post:: <nexus>/bank-transports/<transport-name>/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.
 
-    This one should be implemented last and specified better!
+  **Response:**
 
-  Return a list of previously sent ebics messages together with their status.
-  This allows retrying sending a message, if there was a crash during sending
-  the message.
+  :status 404 Not Found: ``transport-name`` doesn't exist for
+    the requesting user.
diff --git a/libeufin/api-nexus2.rst b/libeufin/api-nexus2.rst
deleted file mode 100644
index 2cd0b2e..0000000
--- a/libeufin/api-nexus2.rst
+++ /dev/null
@@ -1,300 +0,0 @@
-Nexus API
-###########
-
-HTTP API
-========
-
-Authentication
---------------
-
-Currently every request made to nexus must be authenticated using the *HTTP
-basic auth* mechanism.
-
-Other authentication mechanisms (e.g. OpenID Connect) might
-be supported in the future.
-
-Users Management
-----------------
-
-.. http:get:: <nexus>/user
-
-  Get information about the current user (based on the authentication 
information
-  in this request).
-
-  **Response:**
-
-  .. ts:def:: GetUserResponse
-
-     interface UserResponse {
-
-       // User name
-       username: string;
-
-       // Is it a superuser?
-       superuser: boolean;
-     }
-
-.. http:post:: <nexus>/users
-
-  Create a new user.  Only the super-user can call this API.
-
-  **Request:**
-
-  The body is a `User` object.
-
-  **Response:**
-
-  :status 409 Conflict: Username is not available.
-
-  **Details:**
-
-  .. ts:def:: CreateUserRequest
-
-     interface User {
-
-       // User name
-       username: string;
-
-       // Initial password
-       password: string;
-     }
-
-Bank Account Management
------------------------
-
-.. http:get:: <nexus>/bank-accounts
-  
-  **Response:**
-
-  A list of `BankAccount` objects
-  that belong to the requester.
-
-  .. ts:def:: BankAccount
-     
-     interface BankAccount {
-       // mnemonic name identifying this bank account.
-       account: string; 
-       // IBAN
-       iban: string;
-       // BIC
-       bic: string;
-       // Legal subject owning the account.
-       holder: string;
-     }
-
-.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments/submit
-
-  Ask nexus to submit one prepare payment at the bank.
-
-  **Request:**
-
-  .. ts:def:: SubmitPayment
-
-     interface SubmitPayment {
-       // Unique identifier of the (previously) prepared payment
-       // to submit at the bank.
-       uuid: string;
-
-       // Optional field to specify the bank transport to use
-       // for the submission.
-       transport: string;
-     }
-
-  :status 404 Not Found: the unique identifier **or**
-    the bank transport could not be found in the system
-
-
-.. http:get:: <nexus>/bank-accounts/<my-acct>/prepared-payments/$uuid
-   
-   Ask the status of payment ``$uuid``.
-
-   **Response:**
-
-   .. ts:def:: PaymentStatus
-
-      interface PaymentStatus {
-
-        // Payment unique identifier
-        uuid: string;
-
-        // True for submitted payments
-        submitted: boolean;
-
-        // Creditor IBAN
-        creditorIban: string;
-
-        // Creditor BIC
-        creditorBic: string;
-
-        // Creditor legal name
-        creditorName: string;
-
-        // Amount
-        amount: string;
-
-        // Date of submission (in dashed form YYYY-MM-DD)
-        submissionDate: string;
-
-        // Date of preparation (in dashed form YYYY-MM-DD)
-        preparationDate: string;
-      }
-
-.. http:post:: <nexus>/bank-accounts/<my-acct>/prepared-payments
-  
-  Ask nexus to prepare instructions for a new payment.
-  Note that ``my-acct`` is the bank account that will be
-  **debited** after this operation.
-
-  **Request:**
-
-  .. ts:def:: PreparedPaymentRequest
-
-     interface PreparedPayment {
-       // IBAN that will receive the payment.
-       iban: string;
-       // BIC hosting the IBAN.
-       bic: string;
-       // Legal subject that will receive the payment.
-       name: string;
-
-       // amount, in the format CURRENCY:XX.YY
-       amount: string
-     }
-
-  **Response:**
-
-  .. ts:def:: PreparedPaymentResponse
-     
-     interface PreparedPaymentResponse {
-
-       // Opaque identifier to be communicated when
-       // the user wants to submit the payment to the
-       // bank.
-       uuid: string;
-     }
-
-.. http:post:: <nexus>/bank-accounts/<my-acct>/collected-transactions
-
-  Ask the default transport to download the latest transactions
-  related to ``my-acct`` and store them locally.
-
-  **Request:**
-
-  .. ts:def:: CollectTransactions
-
-     interface CollectTransactions {
-       // Optional field to specify the bank transport to
-       // use for such operation.
-       bankTransport?: string;
-       // dashed date (YYYY-MM-DD) of the earliest payment
-       // in the result. Optional, defaults to "earliest
-       // possible" date.
-       start: string;
-       // dashed date (YYYY-MM-DD) of the earliest payment
-       // in the result. Optional, defaults to "latest
-       // possible" date.
-       end: string;
-     }
-
-.. http:get:: <nexus>/bank-accounts/<my-acct>/collected-transactions
-
-  Shows which transactions are stored locally at nexus.
-
-  **Query parameters:**
-
-  * **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
-
-
-  **Response:** A list of `Transaction` objects.
-
-  .. ts:def:: Transaction
-
-     interface Transaction {
-       // local bank account involved in the transaction.
-       account: string;
-
-       // counterpart IBAN
-       counterpartIban: string;
-
-       // counterpart BIC
-       counterpartBic: string;
-
-       // counterpart holder name
-       counterpartName: string;
-
-       // amount, in the format [-]CURRENCY:XX.YY,
-       // where the minus sign as prefix indicates
-       // a debit for the user's bank account.
-       amount: string
-     }
-
-Bank Transports
----------------
-
-Bank transports connect the local LibEuFin bank account
-to the real bank.
-
-.. http:post:: <nexus>/bank-transports
-  
-  Activate a new bank transport for the requesting user.
-
-  **Request:**
-  Object of the type `BankTransport`
-
-  **Response:**
-
-  :status 409 Conflict: The ``name`` field exists already for
-    the requesting user.
-
-  **Details:**
-
-  .. ts:def:: BankTransport
-
-     interface BankTransport {
-
-       // Mnemonic identifier for the transport bein created.
-       name: string;
-
-       // Optional field to restore a previous transport.
-       backup: TransportBackup;
-
-       // Type of the transport (ebics, fints, native, ..)
-       type: string;
-     }
-
-
-  .. ts:def:: TransportBackup
-     
-     interface TransportBackup {
-
-      // The information needed in this type depend entirely
-      // on which transport is being restored.
-
-     }
-
-.. http:post:: <nexus>/bank-transports/<transport-name>/sendMSG.
-  
-  Perform the ``MSG`` operation offered by ``transport-name``
-  **without** affecting the nexus database.
-
-  **Response:**
-
-  :status 404 Not Found: ``transport-name`` doesn't exist for
-    the requesting user.
-
-.. http:post:: <nexus>/bank-transports/<transport-name>/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.
-
-  **Response:**
-
-  :status 404 Not Found: ``transport-name`` doesn't exist for
-    the requesting user.
diff --git a/libeufin/index.rst b/libeufin/index.rst
index e128cf0..bc00b96 100644
--- a/libeufin/index.rst
+++ b/libeufin/index.rst
@@ -9,5 +9,5 @@ LibEuFin is a project providing free software tooling for 
European FinTech.
   concepts
   ebics
   api-sandbox
-  api-nexus2
+  api-nexus
   iso20022

-- 
To stop receiving notification emails like this one, please contact
address@hidden.