Fix pagination documentation for stellar-rpc (#1363)

stellar · Mar 7, 2025 · 34029f1 · 34029f1
1 parent 10ab87e
commit 34029f1
Show file tree

Hide file tree

Showing 10 changed files with 49 additions and 56 deletions.
diff --git a/docs/data/rpc/api-reference/structure/pagination.mdx b/docs/data/rpc/api-reference/structure/pagination.mdx
@@ -7,7 +7,7 @@ Pagination in stellar-rpc is similar to pagination in Horizon.
 
 For methods which support it, the pagination arguments are passed as a final object argument with two values:
 
-- `cursor`: string - (optional) A string ID that points to a specific location in a collection of responses and is pulled from the paging*token value of a record. When a cursor is provided Stellar-RPC will \_not* include the element whose id matches the cursor in the response. Only elements which appear _after_ the cursor are included.
+- `cursor`: string - (optional) An opaque string which acts as a paging token. Each response will include a `cursor` field which can be included in a subsequent request to obtain the next page of results.
 - `limit`: number - (optional) The maximum number of records returned. The limit for [getEvents](../methods/getEvents.mdx) can range from 1 to 10000 - an upper limit that is hardcoded in Stellar-RPC for performance reasons. If this argument isn't designated, it defaults to 100.
 
 For example, calling a method with pagination parameter set:

diff --git a/openrpc/src/stellar-rpc/contentDescriptors/Pagination.json b/openrpc/src/stellar-rpc/contentDescriptors/Pagination.json
@@ -1,20 +1,11 @@
 {
-    "EventsPagination": {
+    "Pagination": {
         "name": "pagination",
         "summary": "pagination options",
-        "description": "Pagination in stellar-rpc is similar to pagination in Horizon. See [Pagination](https://developers.stellar.org/docs/data/rpc/api-reference/pagination).",
+        "description": "Pagination in stellar-rpc is similar to pagination in Horizon. See [Pagination](/docs/data/rpc/api-reference/structure/pagination).",
         "required": false,
         "schema": {
-            "$ref": "#/components/schemas/EventsPagination"
-        }
-    },
-    "TransactionsPagination": {
-        "name": "pagination",
-        "summary": "pagination options",
-        "description": "Pagination in RPC is similar to pagination in Horizon. See [Pagination](https://developers.stellar.org/docs/data/rpc/api-reference/pagination).",
-        "required": false,
-        "schema": {
-            "$ref": "#/components/schemas/TransactionsPagination"
+            "$ref": "#/components/schemas/Pagination"
         }
     }
 }
diff --git a/openrpc/src/stellar-rpc/examples/Events.json b/openrpc/src/stellar-rpc/examples/Events.json
@@ -64,7 +64,8 @@
                     "txHash": "3fa1787085a4aa585507751394d70494a02e71d347446095a763ecbfc647937c"
                 }
             ],
-            "latestLedger": 1197926
+            "latestLedger": 1197926,
+            "cursor": "0005121482212511744-0000000002"
         }
     },
     "AnyTwoEvents": {
@@ -103,7 +104,8 @@
                     "txHash": "3f81b00a78830bb0186539cceed5ac137aad0d6872dd998c533c2758fbda0a6c"
                 }
             ],
-            "latestLedger": 1197964
+            "latestLedger": 1197964,
+            "cursor": "0005111084096696320-0000000001"
         }
     }
 }
diff --git a/openrpc/src/stellar-rpc/methods/getEvents.json b/openrpc/src/stellar-rpc/methods/getEvents.json
@@ -17,7 +17,7 @@
             "$ref": "#/components/contentDescriptors/EventFilters"
         },
         {
-            "$ref": "#/components/contentDescriptors/EventsPagination"
+            "$ref": "#/components/contentDescriptors/Pagination"
         },
         {
             "$ref": "#/components/contentDescriptors/Format"
@@ -39,7 +39,7 @@
                 },
                 "cursor": {
                     "type": "string",
-                    "$ref": "#/components/schemas/GetEventsCursor"
+                    "$ref": "#/components/schemas/Cursor"
                 }
             }
         }

diff --git a/openrpc/src/stellar-rpc/methods/getLedgers.json b/openrpc/src/stellar-rpc/methods/getLedgers.json
@@ -11,7 +11,7 @@
       "$ref": "#/components/contentDescriptors/StartLedger"
     },
     {
-      "$ref": "#/components/contentDescriptors/TransactionsPagination"
+      "$ref": "#/components/contentDescriptors/Pagination"
     },
     {
       "$ref": "#/components/contentDescriptors/Format"
@@ -39,6 +39,10 @@
         },
         "oldestLedgerCloseTime": {
           "$ref": "#/components/schemas/OldestLedgerCloseTime"
+        },
+        "cursor": {
+          "type": "string",
+          "$ref": "#/components/schemas/Cursor"
         }
       }
     }

diff --git a/openrpc/src/stellar-rpc/methods/getTransactions.json b/openrpc/src/stellar-rpc/methods/getTransactions.json
@@ -11,7 +11,7 @@
       "$ref": "#/components/contentDescriptors/StartLedger"
     },
     {
-      "$ref": "#/components/contentDescriptors/TransactionsPagination"
+      "$ref": "#/components/contentDescriptors/Pagination"
     },
     {
       "$ref": "#/components/contentDescriptors/Format"
@@ -39,6 +39,10 @@
         },
         "oldestLedgerCloseTimestamp": {
           "$ref": "#/components/schemas/OldestLedgerCloseTime"
+        },
+        "cursor": {
+          "type": "string",
+          "$ref": "#/components/schemas/Cursor"
         }
       }
     }

diff --git a/openrpc/src/stellar-rpc/schemas/Cursor.json b/openrpc/src/stellar-rpc/schemas/Cursor.json
@@ -2,11 +2,6 @@
   "Cursor": {
     "title": "cursor",
     "type": "string",
-    "description": "A unique identifier (specifically, a [TOID](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0035.md#specification)) that points to a specific location in a collection of responses and is pulled from the `paging_token` value of a record. When a cursor is provided, RPC will _not_ include the element whose ID matches the cursor in the response: only elements which appear _after_ the cursor will be included."
-  },
-  "GetEventsCursor": {
-    "title": "cursor",
-    "type": "string",
-    "description": "The last populated event ID if total events reach the limit or end of the search window."
+    "description": "A token which can be included in a subsequent request to obtain the next page of results."
   }
 }
diff --git a/openrpc/src/stellar-rpc/schemas/Event.json b/openrpc/src/stellar-rpc/schemas/Event.json
@@ -21,7 +21,7 @@
                 "$ref": "#/components/schemas/EventId"
             },
             "pagingToken": {
-                "description": "Duplicate of `id` field, but in the standard place for pagination tokens.",
+                "description": "Duplicate of `id` field. This field is deprecated, please use the `cursor` field at the top level of the getEvents response for pagination.",
                 "$ref": "#/components/schemas/EventId"
             },
             "inSuccessfulContractCall": {

diff --git a/openrpc/src/stellar-rpc/schemas/Pagination.json b/openrpc/src/stellar-rpc/schemas/Pagination.json
@@ -1,28 +1,16 @@
 {
-    "EventsPagination": {
+    "Pagination": {
         "type": "object",
         "properties": {
             "cursor": {
-                "$ref": "#/components/schemas/Cursor"
+                "type": "string",
+                "description": "An opaque string which acts as a paging token. To obtain the next page of results occurring after a given response set this value to the `cursor` field of the response."
             },
             "limit": {
                 "type": "number",
                 "description": "The maximum number of records returned. The limit for getEvents can range from 1 to 10000 - an upper limit that is hardcoded in Stellar-RPC for performance reasons. If this argument isn't designated, it defaults to 100."
             }
         },
         "required": []
-    },
-    "TransactionsPagination": {
-        "type": "object",
-        "properties": {
-            "cursor": {
-                "$ref": "#/components/schemas/Cursor"
-            },
-            "limit": {
-                "type": "number",
-                "description": "The maximum number of records returned by the endpoint."
-            }
-        },
-        "required": []
     }
 }
diff --git a/static/stellar-rpc.openrpc.json b/static/stellar-rpc.openrpc.json
@@ -112,16 +112,15 @@
         {
           "name": "pagination",
           "summary": "pagination options",
-          "description": "Pagination in stellar-rpc is similar to pagination in Horizon. See [Pagination](https://developers.stellar.org/docs/data/rpc/api-reference/pagination).",
+          "description": "Pagination in stellar-rpc is similar to pagination in Horizon. See [Pagination](/docs/data/rpc/api-reference/structure/pagination).",
           "required": false,
           "schema": {
             "type": "object",
             "required": [],
             "properties": {
               "cursor": {
-                "title": "cursor",
                 "type": "string",
-                "description": "A unique identifier (specifically, a [TOID](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0035.md#specification)) that points to a specific location in a collection of responses and is pulled from the `paging_token` value of a record. When a cursor is provided, RPC will _not_ include the element whose ID matches the cursor in the response: only elements which appear _after_ the cursor will be included."
+                "description": "An opaque string which acts as a paging token. To obtain the next page of results occurring after a given response set this value to the `cursor` field of the response."
               },
               "limit": {
                 "type": "number",
@@ -186,7 +185,7 @@
                     "type": "string"
                   },
                   "pagingToken": {
-                    "description": "Duplicate of `id` field, but in the standard place for pagination tokens.",
+                    "description": "Duplicate of `id` field. This field is deprecated, please use the `cursor` field at the top level of the getEvents response for pagination.",
                     "type": "string"
                   },
                   "inSuccessfulContractCall": {
@@ -222,7 +221,7 @@
             "cursor": {
               "title": "cursor",
               "type": "string",
-              "description": "The last populated event ID if total events reach the limit or end of the search window."
+              "description": "A token which can be included in a subsequent request to obtain the next page of results."
             }
           }
         }
@@ -301,7 +300,8 @@
                   "txHash": "3fa1787085a4aa585507751394d70494a02e71d347446095a763ecbfc647937c"
                 }
               ],
-              "latestLedger": 1197926
+              "latestLedger": 1197926,
+              "cursor": "0005121482212511744-0000000002"
             }
           }
         },
@@ -356,7 +356,8 @@
                   "txHash": "3f81b00a78830bb0186539cceed5ac137aad0d6872dd998c533c2758fbda0a6c"
                 }
               ],
-              "latestLedger": 1197964
+              "latestLedger": 1197964,
+              "cursor": "0005111084096696320-0000000001"
             }
           }
         }
@@ -867,20 +868,19 @@
         {
           "name": "pagination",
           "summary": "pagination options",
-          "description": "Pagination in RPC is similar to pagination in Horizon. See [Pagination](https://developers.stellar.org/docs/data/rpc/api-reference/pagination).",
+          "description": "Pagination in stellar-rpc is similar to pagination in Horizon. See [Pagination](/docs/data/rpc/api-reference/structure/pagination).",
           "required": false,
           "schema": {
             "type": "object",
             "required": [],
             "properties": {
               "cursor": {
-                "title": "cursor",
                 "type": "string",
-                "description": "A unique identifier (specifically, a [TOID](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0035.md#specification)) that points to a specific location in a collection of responses and is pulled from the `paging_token` value of a record. When a cursor is provided, RPC will _not_ include the element whose ID matches the cursor in the response: only elements which appear _after_ the cursor will be included."
+                "description": "An opaque string which acts as a paging token. To obtain the next page of results occurring after a given response set this value to the `cursor` field of the response."
               },
               "limit": {
                 "type": "number",
-                "description": "The maximum number of records returned by the endpoint."
+                "description": "The maximum number of records returned. The limit for getEvents can range from 1 to 10000 - an upper limit that is hardcoded in Stellar-RPC for performance reasons. If this argument isn't designated, it defaults to 100."
               }
             }
           }
@@ -951,6 +951,11 @@
               "title": "oldestLedgerCloseTime",
               "description": "The unix timestamp of the close time of the oldest ledger ingested by Stellar RPC at the time it handled the request.",
               "type": "number"
+            },
+            "cursor": {
+              "title": "cursor",
+              "type": "string",
+              "description": "A token which can be included in a subsequent request to obtain the next page of results."
             }
           }
         }
@@ -1277,20 +1282,19 @@
         {
           "name": "pagination",
           "summary": "pagination options",
-          "description": "Pagination in RPC is similar to pagination in Horizon. See [Pagination](https://developers.stellar.org/docs/data/rpc/api-reference/pagination).",
+          "description": "Pagination in stellar-rpc is similar to pagination in Horizon. See [Pagination](/docs/data/rpc/api-reference/structure/pagination).",
           "required": false,
           "schema": {
             "type": "object",
             "required": [],
             "properties": {
               "cursor": {
-                "title": "cursor",
                 "type": "string",
-                "description": "A unique identifier (specifically, a [TOID](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0035.md#specification)) that points to a specific location in a collection of responses and is pulled from the `paging_token` value of a record. When a cursor is provided, RPC will _not_ include the element whose ID matches the cursor in the response: only elements which appear _after_ the cursor will be included."
+                "description": "An opaque string which acts as a paging token. To obtain the next page of results occurring after a given response set this value to the `cursor` field of the response."
               },
               "limit": {
                 "type": "number",
-                "description": "The maximum number of records returned by the endpoint."
+                "description": "The maximum number of records returned. The limit for getEvents can range from 1 to 10000 - an upper limit that is hardcoded in Stellar-RPC for performance reasons. If this argument isn't designated, it defaults to 100."
               }
             }
           }
@@ -1380,6 +1384,11 @@
               "title": "oldestLedgerCloseTime",
               "description": "The unix timestamp of the close time of the oldest ledger ingested by Stellar RPC at the time it handled the request.",
               "type": "number"
+            },
+            "cursor": {
+              "title": "cursor",
+              "type": "string",
+              "description": "A token which can be included in a subsequent request to obtain the next page of results."
             }
           }
         }