get-private-fountains.rst (2476B)
1 .. http:get:: [/instances/$INSTANCE]/private/fountains 2 3 Lists a bounded page of fountains of the instance, ordered by 4 ``fountain_serial``. 5 This endpoint is available since protocol **v43**. Pagination and the 6 ``fountain_serial`` response field are available since protocol **v44**. 7 Clients must iterate over the pages to retrieve all fountains. 8 9 **Required permission:** ``fountains-read`` (see :ref:`Scopes <merchant-api-scopes>`) 10 11 **Request:** 12 13 :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. 14 :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. 15 16 To iterate, use the last entry's ``fountain_serial`` as the ``offset`` 17 of the next request, keeping the same ``limit``. Stop when a page is 18 empty. For example, start with ``?limit=20`` and continue with 19 ``?limit=20&offset=42`` if the last returned serial is ``42``. 20 Each request reads the current database state; the iteration does not 21 provide a snapshot across requests. 22 23 **Response:** 24 25 :http:statuscode:`200 OK`: 26 The backend has successfully returned a page of at most 100 fountains. 27 Returns a `FountainsListResponse`. 28 :http:statuscode:`400 Bad request`: 29 A pagination parameter is malformed or outside its permitted range. 30 :http:statuscode:`404 Not found`: 31 The merchant instance is unknown. 32 :http:statuscode:`500 Internal Server Error`: 33 The server experienced an internal failure. 34 35 **Details:** 36 37 .. ts:def:: FountainsListResponse 38 39 interface FountainsListResponse { 40 41 // The requested page of fountains, in serial order. 42 fountains: FountainEntry[]; 43 } 44 45 .. ts:def:: FountainEntry 46 47 interface FountainEntry { 48 49 // Database serial number used as an exclusive pagination cursor. 50 // Since protocol **v44**. 51 fountain_serial: Integer; 52 53 // Identifier of the fountain. 54 fountain_id: Slug; 55 56 // Human-readable description of the fountain. 57 description: string; 58 }