commit 63b675a7f1f55b1d31618ff668e28ea5e4d30a71
parent 5875b7ec4b95bf8ee769739f6ac99b69dfe5345f
Author: Christian Grothoff <christian@grothoff.org>
Date: Fri, 27 Feb 2026 22:22:43 +0100
add version documentation for each API (#9441)
Diffstat:
18 files changed, 347 insertions(+), 28 deletions(-)
diff --git a/core/api-auditor.rst b/core/api-auditor.rst
@@ -24,6 +24,28 @@ for all details not specified in the individual requests.
The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
defines all specific terms used in this section.
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v2**.
+
+* The auditor SPA currently targeting protocol version **v1**.
+
+**Version history:**
+
+* ``v2``: Adds a few additional GET endpoints to expose more auditor data
+
+**Upcoming versions:**
+
+* none anticipated
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
.. _authentication:
--------------
diff --git a/core/api-bank-account-directory.rst b/core/api-bank-account-directory.rst
@@ -20,10 +20,30 @@ Taler Account Directory API
This chapter describes the account discovery API that wallets or other clients can use to help the user find their payto URI.
+---------------
+Version History
+---------------
+
+The current protocol version is **v1**.
+
+* Nothing depends on the bank account directory API at this point.
+
+**Version history:**
+
+* ``v1``: Initial version.
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being **v1**.
**Response:**
diff --git a/core/api-bank-conversion-info.rst b/core/api-bank-conversion-info.rst
@@ -26,10 +26,27 @@ This chapter describes the conversion info API. The conversion info API
is used by wallets for withdrawals that involve a currency conversion.
+The current protocol version is **v2**.
+
+* The wallet-core is currently targeting protocol version **v2**.
+
+**Version history:**
+
+* ``v2``: adds ``/rate`` endpoint
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
+
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being **v2**.
**Response:**
@@ -67,8 +84,8 @@ is used by wallets for withdrawals that involve a currency conversion.
// How the bank SPA should render this currency.
fiat_currency_specification: CurrencySpecification;
- // Global exchange rate between the regional currency and the fiat
- // currency of the banking system. Use /rate to get the user specific
+ // Global exchange rate between the regional currency and the fiat
+ // currency of the banking system. Use /rate to get the user specific
// rate.
conversion_rate: ConversionRate;
}
@@ -78,9 +95,9 @@ is used by wallets for withdrawals that involve a currency conversion.
Since protocol **v2**.
This public endpoint allows clients to get the currenlty applied change rate between the regional currency and the fiat currency of the banking system for this exchange account.
- Those informations should never be used to perform conversions use /cashin-rate and /cashout-rate instead.
- Conversion rates can change at any time. Clients must deal with any resulting errors and call /cashin-rate or /cashout-rate again to use the new rates.
- If cashin_ratio is zero, this means the account cannot cashin, and if cash_out ratio is zero, this means the account cannot cashout.
+ Those informations should never be used to perform conversions use ``/cashin-rate`` and ``/cashout-rate`` instead.
+ Conversion rates can change at any time. Clients must deal with any resulting errors and call ``/cashin-rate`` or ``/cashout-rate`` again to use the new rates.
+ If ``cashin_ratio`` is zero, this means the account cannot cashin, and if ``cash_out`` ratio is zero, this means the account cannot cashout.
**Response:**
@@ -89,6 +106,8 @@ is used by wallets for withdrawals that involve a currency conversion.
:http:statuscode:`501 Not implemented`:
This server does not support conversion.
+.. _cashin-rates:
+
.. http:get:: /cashin-rate
This public endpoint allows clients to calculate
@@ -140,6 +159,8 @@ is used by wallets for withdrawals that involve a currency conversion.
amount_credit: Amount;
}
+.. _cashout-rates:
+
.. http:get:: /cashout-rate
This public endpoint allows clients to calculate
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -24,10 +24,32 @@ Taler Bank Integration API
This chapter describe the APIs that banks need to offer towards Taler wallets
to tightly integrate with GNU Taler.
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v5**.
+
+* The wallet-core is currently targeting protocol version **v4**.
+
+**Version history:**
+
+* ``v5``: adds ``no_amount_to_wallet`` flag to the WOPID status
+
+**Upcoming versions:**
+
+* ``vSHORT``: support for short wire transfer subjects?
+* ``vPERIODIC``: support for periodic wire transfers?
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being **v5**.
**Response:**
diff --git a/core/api-bank-revenue.rst b/core/api-bank-revenue.rst
@@ -22,10 +22,31 @@ Taler Bank Revenue HTTP API
This section describes an API offered by libeufin-nexus and libeufin-bank. The API is
used by the merchant (or other parties) to query for incoming transactions to their account.
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v1**.
+
+* The merchant is currently targeting protocol version **v1**.
+
+**Version history:**
+
+* ``v1``: pagination API consistency fixes
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **1**.
**Response:**
diff --git a/core/api-challenger.rst b/core/api-challenger.rst
@@ -84,6 +84,28 @@ verified address of the user.
.. contents:: Table of Contents
:local:
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v6**.
+
+* The Challenger SPA is currently targeting **v6**.
+
+**Version history:**
+
+* ``v6``: add the ``address_type`` field to ``/config``
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
.. include:: tos.rst
.. _challenger-config:
@@ -95,7 +117,6 @@ Receiving Configuration
.. http:get:: /config
Obtain the key configuration settings of the storage service.
- This specification corresponds to ``current`` protocol being version **v6**.
**Response:**
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -31,14 +31,25 @@ it provides features for local/regional currencies.
Version History
---------------
-The current protocol version is ``v11``.
+The current protocol version is **v11**.
-Android cashier app is currently targeting ``v9``.
+* Android cashier app is currently targeting **v9**.
**Version history:**
-* ``v11``: Add observability API
* ``v10``: Update two factor authentication API to match Merchant Backend API
+* ``v11``: Add observability API
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
+
Config
------
@@ -1689,7 +1700,7 @@ Requesting challenges
Solving challenges
^^^^^^^^^^^^^^^^^^
-
+
.. http:post:: /accounts/$USERNAME/challenge/$CHALLENGE_ID/confirm
Solves the ``CHALLENGE_ID`` challenge and allows performing the protected operation.
diff --git a/core/api-donau.rst b/core/api-donau.rst
@@ -31,6 +31,8 @@ defines all specific terms used in this section.
.. _donau-overview:
+
+
------------
API Overview
------------
@@ -48,6 +50,29 @@ The chapters group the families of requests frequently encountered when using th
* For use by administrators to add/modify a charity
* For use by charities to get their remaining donation volume
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v0**.
+
+* The merchant is currently targeting protocol version **v0**.
+* The donau validator app is currently targeting protocol version **v0**.
+
+**Version history:**
+
+* ``v0``: This is the first implementation.
+
+**Upcoming versions:**
+
+* none anticipated
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
.. include:: tos.rst
.. _donau_status:
diff --git a/core/api-ebisync.rst b/core/api-ebisync.rst
@@ -24,7 +24,23 @@ Taler EbiSync RESTful API
Version History
---------------
-The current protocol version is ``v0``.
+The current protocol version is **v0**.
+
+* Nothing depends on the ebisync API at this point.
+
+**Version history:**
+
+* ``v0``: Initial version.
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
Introduction
------------
diff --git a/core/api-exchange.rst b/core/api-exchange.rst
@@ -25,6 +25,35 @@ for all details not specified in the individual requests.
The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
defines all specific terms used in this section.
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v32**.
+
+* The merchant is currently targeting **v32**.
+* The AML SPA is currently targeting **v31**.
+* The KYC SPA is currently targeting **v30**.
+
+**Version history:**
+
+* ``v29``: AML reporting on KYC auth transfers
+* ``v30``: various minor feature additions
+* ``v31``: improvements for AML reporting
+* ``v32``: support for extra_wire_subject_metadata
+
+**Upcoming versions:**
+
+* ``vRECOUP``: improved recoup protocol
+* ``vATTEST``: KYC attestation support
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
+
.. include:: tos.rst
.. _keys:
@@ -46,15 +75,11 @@ possibly by using HTTPS.
.. include:: exchange/get-seed.rst
-
.. include:: exchange/get-config.rst
-
.. include:: exchange/get-keys.rst
-
-
----------------------------------------------
Management operations authorized by master key
----------------------------------------------
diff --git a/core/api-mailbox.rst b/core/api-mailbox.rst
@@ -36,6 +36,29 @@ for all details not specified in the individual requests.
The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
defines all specific terms used in this section.
+
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v0**.
+
+* Nothing depends on the mailbox API at this point.
+
+**Version history:**
+
+* ``v0``: Initial version.
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
.. include:: tos.rst
-------------------------
@@ -366,5 +389,3 @@ Receiving messages
head of the mailbox, or ``count`` is larger
than the number of messages currently in the mailbox.
This response comes with a standard `ErrorDetail` response.
-
-
diff --git a/core/api-merchant.rst b/core/api-merchant.rst
@@ -29,9 +29,16 @@ Merchant Backend RESTful API
Version History
---------------
-The current protocol version is **v26**.
+The current protocol version is **v27**.
-Android PoS app is currently targeting **v20**.
+* The Android PoS app is currently targeting **v20**.
+* The SPA is currently targeting **vXX**.
+* taler-mdb is currently targeting **v27**.
+* anastasis is currently targeting **v27**.
+* taler-woocommerce is currently targeting **vXX**.
+* taler-drupal-turnstile is currently targeting **vXX**.
+* taler-drupal-commerce is currently targeting **vXX**.
+* paivana is currently targeting **vXX**.
**Version history:**
@@ -45,6 +52,7 @@ Android PoS app is currently targeting **v20**.
new long-polling for KYC and features for templates to support
session-based payments
* ``v26``: adds unclaim endpoint, enhanced settlement reporting
+* ``v27``: adds various fields to a few endpoints
**Upcoming versions:**
diff --git a/core/api-observability.rst b/core/api-observability.rst
@@ -28,13 +28,33 @@ Introduction
This section describes the API offered by many Taler components. The API is
used to track the internal state of a Taler component.
+---------------
+Version History
+---------------
+
+The current protocol version is **v0**.
+
+* This API is to be used by Prometheus and other external tools.
+
+**Version history:**
+
+* ``v0``: Initial version.
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
Config
------
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **v0**.
**Response:**
diff --git a/core/api-sync.rst b/core/api-sync.rst
@@ -106,6 +106,27 @@ keys.
:local:
+---------------
+Version History
+---------------
+
+The current protocol version is **v2**.
+
+* No components use Sync at this point, so there are no dependencies.
+
+**Version history:**
+
+* ``v2``: add the ``implementation`` field to ``/config``
+
+**Upcoming versions:**
+
+* ``vBLOBS``: changes for blob backups
+* ``vBACKUP``: changes for incremental backups
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
.. include:: tos.rst
-----------------------
@@ -115,7 +136,6 @@ Receiving Configuration
.. http:get:: /config
Obtain the key configuration settings of the storage service.
- This specification corresponds to ``current`` protocol being version **2**.
**Response:**
@@ -142,7 +162,7 @@ Receiving Configuration
version: string;
// URN of the implementation (needed to interpret 'revision' in version).
- // @since v2, may become mandatory in the future.
+ // @since **v2**, may become mandatory in the future.
implementation?: string;
}
diff --git a/core/api-taldir.rst b/core/api-taldir.rst
@@ -38,6 +38,30 @@ for all details not specified in the individual requests.
The `glossary <https://docs.taler.net/taler-developer-manual.html#developer-glossary>`_
defines all specific terms used in this section.
+
+
+---------------
+Version History
+---------------
+
+The current protocol version is **v0**.
+
+* Nothing depends on the mailbox API at this point.
+
+**Version history:**
+
+* ``v0``: Initial version.
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
+
.. include:: tos.rst
diff --git a/core/api-terminal.rst b/core/api-terminal.rst
@@ -37,6 +37,30 @@ Implementations of this API typically interact with a terminal-specific
payment service (or a bank) to realize the service.
+---------------
+Version History
+---------------
+
+The current protocol version is **v0**.
+
+* cash2ecash is currently targeting protocol version **v0**.
+* cashless2ecash is currently targeting protocol version **v0**.
+
+**Version history:**
+
+* ``v0``: Initial version.
+
+**Upcoming versions:**
+
+* None anticipated.
+
+**Ideas for future version:**
+
+* ``vXXX``: marker for features not yet targeted for release
+
+
+
+
Authentication
--------------
diff --git a/core/auditor/get-config.rst b/core/auditor/get-config.rst
@@ -1,7 +1,6 @@
.. http:get:: /config
Get the protocol version and some meta data about the auditor.
- This specification corresponds to ``current`` protocol being version **v2**.
**Response:**
diff --git a/core/exchange/get-config.rst b/core/exchange/get-config.rst
@@ -4,7 +4,6 @@
as well as the list of possible KYC requirements. This endpoint is largely
for the SPA for AML officers. Merchants should use ``/keys`` which also
contains the protocol version and currency.
- This specification corresponds to ``current`` protocol being **v32**.
**Response:**
