taler-docs

commit cb9f87f6db83a3db20c11276512a5906195b667b
parent 078601848f8b06cf283180f6481a9090a99d0850
Author: Bohdan Potuzhnyi <potub1@bfh.ch>
Date:   Sat, 10 Oct 2026 22:47:37 +0000

fixing the pagination for /fountains

Diffstat:
M
core/merchant/get-private-fountains.rst
 | 
24
+++++++++++++++++++++---
M
design-documents/098-token-fountains.rst
 | 
3
++-

2 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/core/merchant/get-private-fountains.rst b/core/merchant/get-private-fountains.rst
@@ -1,15 +1,30 @@
 .. http:get:: [/instances/$INSTANCE]/private/fountains
 
-  Lists all fountains of the instance.
+  Lists a bounded page of fountains of the instance, ordered by
+  ``fountain_serial``.
   This endpoint is available since protocol **vTokenFountains**.
 
   **Required permission:** ``fountains-read`` (see :ref:`Scopes <merchant-api-scopes>`)
 
+  **Request:**
+
+  :query limit: *Optional*. Signed 64-bit integer specifying the page size and order. Positive values select ascending serial order; negative values select descending serial order. The default is ``20``. The absolute page size is capped at ``100``, including when a larger magnitude is requested. Zero returns an empty page.
+  :query offset: *Optional*. Exclusive ``fountain_serial`` cursor, an integer between ``0`` and ``9223372036854775807``. Defaults to ``0`` for non-negative limits and ``9223372036854775807`` for negative limits. Ascending pages contain serials greater than the cursor; descending pages contain serials less than the cursor.
+
+  To iterate, use the last entry's ``fountain_serial`` as the ``offset``
+  of the next request, keeping the same ``limit``. Stop when a page is
+  empty. For example, start with ``?limit=20`` and continue with
+  ``?limit=20&offset=42`` if the last returned serial is ``42``.
+  Each request reads the current database state; the iteration does not
+  provide a snapshot across requests.
+
   **Response:**
 
   :http:statuscode:`200 OK`:
-    The backend has successfully returned the list of fountains.
+    The backend has successfully returned a page of at most 100 fountains.
     Returns a `FountainsListResponse`.
+  :http:statuscode:`400 Bad request`:
+    A pagination parameter is malformed or outside its permitted range.
   :http:statuscode:`404 Not found`:
     The merchant instance is unknown.
   :http:statuscode:`500 Internal Server Error`:
@@ -21,7 +36,7 @@
 
     interface FountainsListResponse {
 
-      // All fountains of this instance.
+      // The requested page of fountains, in serial order.
       fountains: FountainEntry[];
     }
 
@@ -29,6 +44,9 @@
 
     interface FountainEntry {
 
+      // Database serial number used as an exclusive pagination cursor.
+      fountain_serial: Integer;
+
       // Identifier of the fountain.
       fountain_id: Slug;
 
diff --git a/design-documents/098-token-fountains.rst b/design-documents/098-token-fountains.rst
@@ -200,7 +200,8 @@ delete fountains:
 
 * ``POST /private/fountains``
 
-* ``GET /private/fountains``
+* ``GET /private/fountains`` (paginated listing ordered by fountain serial;
+  defaults to 20 entries, with a hard cap of 100 per request)
 
 * ``GET /private/fountains/$FOUNTAIN_ID``