commit a73972c06308e1f955902eb559ac0287a930b083
parent efec0ea0957f46fc658f19aaa9e1b6b771580386
Author: Antoine A <>
Date: Tue, 6 Aug 2024 12:25:14 +0200
Fix consistency of pagination and long polling
Diffstat:
7 files changed, 147 insertions(+), 139 deletions(-)
diff --git a/core/api-bank-integration.rst b/core/api-bank-integration.rst
@@ -84,7 +84,7 @@ for the withdrawal operation (the ``WITHDRAWAL_ID``) to interact with the withdr
response. A client must never rely on this behavior, as the bank may
return a response immediately.
:query old_state:
- *Optional.* Default to "pending".
+ *Optional.* Defaults to "pending".
**Response:**
diff --git a/core/api-bank-revenue.rst b/core/api-bank-revenue.rst
@@ -25,7 +25,7 @@ used by the merchant (or other parties) to query for incoming transactions to th
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **0**.
+ This specification corresponds to ``current`` protocol being version **1**.
**Response:**
@@ -75,37 +75,22 @@ Querying the transaction history
might come from a "virtual" account, where multiple real bank accounts are
merged into one history.
- Transactions are identified by an opaque numeric identifier, referred to here
- as *row ID*. The semantics of the row ID (including its sorting order) are
- determined by the bank server and completely opaque to the client.
-
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
-
- * If *delta* is positive, return a list of up to *delta* transactions (all matching
- the filter criteria) strictly **after** the starting point. The transactions are sorted
- in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions (all matching
- the filter criteria) strictly **before** the starting point. The transactions are sorted
- in **descending** order of the row ID.
-
- If *starting point* is not explicitly given, it defaults to:
-
- * A value that is **smaller** than all other row IDs if *delta* is **positive**.
- * A value that is **larger** than all other row IDs if *delta* is **negative**.
+ Transactions are identified by an opaque ``row_id`` numerical identifier. Its semantics (including its sorting order) are determined by the bank server and are completely opaque to the client.
**Request:**
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v1.
+ :query offset: *Optional.*
+ Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v1.
+ :query timeout_ms: *Optional.*
+ Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol v1.
+ :query delta: *Optional.*
+ Deprecated in protocol v1. Use *limit* instead.
:query start: *Optional.*
- Row identifier to explicitly set the *starting point* of the query.
- :query delta:
- The *delta* value that determines the range of the query.
- :query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to ``long_poll_ms``
- milliseconds for new transactions that match the query to arrive and only
- then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
- of ``long_poll_ms``.
+ Deprecated in protocol v1. Use *offset* instead.
+ :query long_poll_ms: *Optional.*
+ Deprecated in protocol v1. Use *timeout_ms* instead.
**Response:**
diff --git a/core/api-bank-wire.rst b/core/api-bank-wire.rst
@@ -29,7 +29,7 @@ LibEuFin (work in progress).
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **1**.
+ This specification corresponds to ``current`` protocol being version **2**.
**Response:**
@@ -153,41 +153,24 @@ Querying the transaction history
report it to the exchange, and send funds back to the sender if possible.
The bank account of the exchange is determined via the base URL and/or the
- user name in the ``Authorization`` header. In fact the transaction history
+ user name in the ``Authorization`` header. In fact, the transaction history
might come from a "virtual" account, where multiple real bank accounts are
merged into one history.
- Transactions are identified by an opaque numeric identifier, referred to here
- as *row ID*. The semantics of the row ID (including its sorting order) are
- determined by the bank server and completely opaque to the client.
-
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
-
- * If *delta* is positive, return a list of up to *delta* transactions (all matching
- the filter criteria) strictly **after** the starting point. The transactions are sorted
- in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions (all matching
- the filter criteria) strictly **before** the starting point. The transactions are sorted
- in **descending** order of the row ID.
-
- If *starting point* is not explicitly given, it defaults to:
-
- * A value that is **smaller** than all other row IDs if *delta* is **positive**.
- * A value that is **larger** than all other row IDs if *delta* is **negative**.
-
**Request:**
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v2.
+ :query offset: *Optional.*
+ Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v2.
+ :query timeout_ms: *Optional.*
+ Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol v2.
+ :query delta: *Optional.*
+ Deprecated in protocol v2. Use *limit* instead.
:query start: *Optional.*
- Row identifier to explicitly set the *starting point* of the query.
- :query delta:
- The *delta* value that determines the range of the query.
- :query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to ``long_poll_ms``
- milliseconds for new transactions that match the query to arrive and only
- then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
- of ``long_poll_ms``.
+ Deprecated in protocol v2. Use *offset* instead.
+ :query long_poll_ms: *Optional.*
+ Deprecated in protocol v2. Use *timeout_ms* instead.
**Response:**
@@ -301,42 +284,25 @@ Querying the transaction history
Return a list of transactions made by the exchange, typically to a merchant.
The bank account of the exchange is determined via the base URL and/or the
- user name in the ``Authorization`` header. In fact the transaction history
+ user name in the ``Authorization`` header. In fact, the transaction history
might come from a "virtual" account, where multiple real bank accounts are
merged into one history.
- Transactions are identified by an opaque integer, referred to here as *row
- ID*. The semantics of the row ID (including its sorting order) are
- determined by the bank server and completely opaque to the client.
-
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
-
- * If *delta* is positive, return a list of up to *delta* transactions (all matching
- the filter criteria) strictly **after** the starting point. The transactions are sorted
- in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions (all matching
- the filter criteria) strictly **before** the starting point. The transactions are sorted
- in **descending** order of the row ID.
-
- If *starting point* is not explicitly given, it defaults to:
-
- * A value that is **smaller** than all other row IDs if *delta* is **positive**.
- * A value that is **larger** than all other row IDs if *delta* is **negative**.
-
**Request:**
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v2.
+ :query offset: *Optional.*
+ Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v2.
+ :query timeout_ms: *Optional.*
+ Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol v2.
+ :query delta: *Optional.*
+ Deprecated in protocol v2. Use *limit* instead.
:query start: *Optional.*
- Row identifier to explicitly set the *starting point* of the query.
- :query delta:
- The *delta* value that determines the range of the query.
- :query long_poll_ms: *Optional.* If this parameter is specified and the
- result of the query would be empty, the bank will wait up to ``long_poll_ms``
- milliseconds for new transactions that match the query to arrive and only
- then send the HTTP response. A client must never rely on this behavior, as
- the bank may return a response immediately or after waiting only a fraction
- of ``long_poll_ms``.
-
+ Deprecated in protocol v2. Use *offset* instead.
+ :query long_poll_ms: *Optional.*
+ Deprecated in protocol v2. Use *timeout_ms* instead.
+
**Response:**
:http:statuscode:`200 OK`:
diff --git a/core/api-common.rst b/core/api-common.rst
@@ -191,7 +191,6 @@ Examples:
sent to the service. Instead, the client should just use the two version ranges
to decide whether it will talk to the service.
-
.. _error-codes:
-----------
@@ -214,6 +213,59 @@ In C, the respective enumeration is the ``enum TALER_ErrorCode``.
Developers may have to re-run ``bootstrap`` and/or update their Git
submodules to ensure that they have the lastest GANA registry.
+---------------------
+Common query patterns
+---------------------
+
+.. _row-id-pagination:
+
+Row ID pagination
+^^^^^^^^^^^^^^^^^
+
+Some endpoints paginate elements identified by an opaque numeric identifier,
+referred to here as *row ID*. The semantics of the row ID (including its
+sorting order) are determined by the server and are completely opaque to the
+client.
+
+The list of returned elements is determined by a row ID *offset*
+and a non-zero signed integer *limit*:
+
+* If *limit* is positive, return a list of up to *limit* elements (all matching
+ the filter criteria) strictly **after** the *offset*. The elements are sorted
+ in **ascending** order of the row ID.
+* If *limit* is negative, return a list of up to *-limit* elements (all matching
+ the filter criteria) strictly **before** the *offset*. The elements are sorted
+ in **descending** order of the row ID.
+
+If *offset* is not explicitly given, it defaults to:
+
+* A value **smaller** than all other row IDs if *limit* is **positive**.
+* A value **larger** than all other row IDs if *limit* is **negative**.
+
+:query limit: *Optional.*
+ At most return the given number of results. Negative for descending by row
+ ID, positive for ascending by row ID.
+:query offset: *Optional.*
+ Starting row ID for an iteration.
+
+.. _long-polling:
+
+Long polling
+^^^^^^^^^^^^
+
+Endpoints can result in an empty response (pagination) or a negative response
+(uncompleted operation, etc). Some endpoints allow clients to perform a form of
+long polling by asking the server to wait until *timeout_ms* for a non-empty or
+positive result.
+
+In the case of pagination, the response is sent as soon as a matching element
+is found and, therefore, the response MAY contain fewer than *limit* elements.
+
+A client MUST never rely on this behavior, as a response can be sent
+immediately or after waiting only a fraction of *timeout_ms*.
+
+:query timeout_ms: *Optional.*
+ Timeout in milliseconds to wait for the response to be non-empty or positive.
.. _encodings-ref:
diff --git a/core/api-corebank.rst b/core/api-corebank.rst
@@ -168,7 +168,7 @@ Config
.. http:get:: /config
Return the protocol version and configuration information about the bank.
- This specification corresponds to ``current`` protocol being version **4**.
+ This specification corresponds to ``current`` protocol being version **5**.
**Response:**
@@ -231,7 +231,7 @@ Config
supported_tan_channels: TanChannel[];
// Wire transfer type supported by the bank.
- // Default to 'iban' is missing
+ // Defaults to 'iban' is missing
// @since v4, will become mandatory in the next version.
wire_type?: string;
@@ -482,15 +482,19 @@ Account Management
**Request:**
- :query delta: *Optional.*
- Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries.
- :query start: *Optional.*
- Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v5.
+ :query offset: *Optional.*
+ Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query filter_name: *Optional.*
- Pattern to filter on the account legal name. Given
+ Pattern to filter on the account's legal name. Given
the filter 'foo', all the results will **contain**
'foo' in their legal name. Without this option,
all the existing accounts are returned.
+ :query delta: *Optional.*
+ Deprecated in protocol v5. Use *limit* instead.
+ :query start: *Optional.*
+ Deprecated in protocol v5. Use *offset* instead.
**Response:**
@@ -536,15 +540,19 @@ Account Management
**Request:**
- :query delta: *Optional.*
- Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries.
- :query start: *Optional.*
- Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v5.
+ :query offset: *Optional.*
+ Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query filter_name: *Optional.*
- Pattern to filter on the account legal name. Given
+ Pattern to filter on the account's legal name. Given
the filter 'foo', all the results will **contain**
'foo' in their legal name. Without this option,
all the existing accounts are returned.
+ :query delta: *Optional.*
+ Deprecated in protocol v5. Use *limit* instead.
+ :query start: *Optional.*
+ Deprecated in protocol v5. Use *offset* instead.
**Response:**
@@ -608,7 +616,7 @@ Account Management
// active: the account can be used
// deleted: the account has been deleted but is retained for compliance
// reasons, only the administrator can access it
- // Default to 'active' is missing
+ // Defaults to 'active' is missing
// @since v4, will become mandatory in the next version.
status?: "active" | "deleted";
}
@@ -680,7 +688,7 @@ Account Management
// active: the account can be used
// deleted: the account has been deleted but is retained for compliance
// reasons, only the administrator can access it
- // Default to 'active' is missing
+ // Defaults to 'active' is missing
// @since v4, will become mandatory in the next version.
status?: "active" | "deleted";
}
@@ -692,30 +700,20 @@ Transactions
Retrieve a subset of transactions related to $USERNAME.
- The list of returned transactions is determined by a row ID *starting point*
- and a signed non-zero integer *delta*:
-
- * If *delta* is positive, return a list of up to *delta* transactions (all matching
- the filter criteria) strictly **after** the starting point. The transactions are sorted
- in **ascending** order of the row ID.
- * If *delta* is negative, return a list of up to *-delta* transactions (all matching
- the filter criteria) strictly **before** the starting point. The transactions are sorted
- in **descending** order of the row ID.
-
- If *starting point* is not explicitly given, it defaults to:
-
- * A value that is **smaller** than all other row IDs if *delta* is **positive**.
- * A value that is **larger** than all other row IDs if *delta* is **negative**.
-
**Request:**
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``row_id``, positive for ascending by ``row_id``. Defaults to ``-20``. Since protocol v5.
+ :query offset: *Optional.*
+ Starting ``row_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
+ :query timeout_ms: *Optional.*
+ Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for at least one element to be shown. Only useful if *limit* is positive. Since protocol v5.
:query delta: *Optional.*
- Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries.
+ Deprecated in protocol v5. Use *limit* instead.
:query start: *Optional.*
- Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
- :query long_poll_ms: Optional number to express how many milliseconds the server
- should wait for at least one result to be shown. If not given, the server
- responds immediately, regardless of the result.
+ Deprecated in protocol v5. Use *offset* instead.
+ :query long_poll_ms: *Optional.*
+ Deprecated in protocol v5. Use *timeout_ms* instead.
**Response:**
@@ -907,14 +905,13 @@ Account withdrawals
serves as an authenticator.
**Request:**
-
- :query long_poll_ms:
- *Optional.* If specified, the bank will wait up to ``long_poll_ms``
- milliseconds for operationt state to be different from ``old_state`` before sending the HTTP
- response. A client must never rely on this behavior, as the bank may
- return a response immediately.
+
:query old_state:
- *Optional.* Default to "pending".
+ *Optional.* Defaults to "pending".
+ :query timeout_ms: *Optional.*
+ Timeout in milliseconds, for :ref:`long-polling <long-polling>`, to wait for the operation state to be different from *old_state*. Since protocol v5.
+ :query long_poll_ms: *Optional.*
+ Deprecated in protocol v5. Use *timeout_ms* instead.
**Response:**
@@ -1081,10 +1078,14 @@ Cashouts
**Request:**
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``cashout_id``, positive for ascending by ``cashout_id``. Defaults to ``-20``. Since protocol v5.
+ :query offset: *Optional.*
+ Starting ``cashout_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query delta: *Optional.*
- Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries.
+ Deprecated in protocol v5. Use *limit* instead.
:query start: *Optional.*
- Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
+ Deprecated in protocol v5. Use *offset* instead.
**Response:**
@@ -1118,10 +1119,14 @@ Cashouts
**Request:**
+ :query limit: *Optional.*
+ At most return the given number of results. Negative for descending by ``cashout_id``, positive for ascending by ``cashout_id``. Defaults to ``-20``. Since protocol v5.
+ :query offset: *Optional.*
+ Starting ``cashout_id`` for :ref:`pagination <row-id-pagination>`. Since protocol v5.
:query delta: *Optional.*
- Takes value of the form ``N (-N)``, so that at most ``N`` values strictly older (younger) than ``start`` are returned. Defaults to ``-20`` to return the last 20 entries.
+ Deprecated in protocol v5. Use *limit* instead.
:query start: *Optional.*
- Row number threshold, see ``delta`` for its interpretation. Defaults to smallest or biggest row id possible according to ``delta`` sign.
+ Deprecated in protocol v5. Use *offset* instead.
.. note::
@@ -1254,13 +1259,13 @@ Monitor
* year
:query date_s: *Optional*.
- Non-negative date in seconds after the UNIX Epoch. Default to current time.
+ Non-negative date in seconds after the UNIX Epoch. Defaults to current time.
@since v4
:query which: *Optional*.
This parameter points at a particular element of the *timeframe* parameter.
Following are the admitted values for each one.
- Default to the last snapshot taken of the *timeframe* parameter.
+ Defaults to the last snapshot taken of the *timeframe* parameter.
@deprecated since v4
* hour: from 00 to 23
diff --git a/core/api-terminal.rst b/core/api-terminal.rst
@@ -311,7 +311,7 @@ Config
response. A client must never rely on this behavior, as the bank may
return a response immediately.
:query old_state:
- *Optional.* Default to "pending".
+ *Optional.* Defaults to "pending".
**Response:**
diff --git a/manpages/libeufin-bank.conf.5.rst b/manpages/libeufin-bank.conf.5.rst
@@ -45,7 +45,7 @@ X_TALER_BANK_PAYTO_HOSTNAME
Bank hostname used in generated x-taler-bank payto URI. Required if ``WIRE_TYPE``is ``x-taler-bank``
NAME
- Bank display name, used in webui and TAN messages. Default to ``Taler Bank`` if not specified.
+ Bank display name, used in webui and TAN messages. Defaults to ``Taler Bank`` if not specified.
BASE_URL
The advertised base URL
