Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix pagination documentation for stellar-rpc #1363

Merged
merged 2 commits into from
Mar 7, 2025
Merged

Fix pagination documentation for stellar-rpc #1363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d12cd8f
Fix pagination documentation for stellar-rpc
tamirms Mar 6, 2025
1135800
code review fixes
tamirms Mar 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/data/rpc/api-reference/structure/pagination.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
15 changes: 3 additions & 12 deletions openrpc/src/stellar-rpc/contentDescriptors/Pagination.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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"
}
}
}
6 changes: 4 additions & 2 deletions openrpc/src/stellar-rpc/examples/Events.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,8 @@
"txHash": "3fa1787085a4aa585507751394d70494a02e71d347446095a763ecbfc647937c"
}
],
"latestLedger": 1197926
"latestLedger": 1197926,
"cursor": "0005121482212511744-0000000002"
}
},
"AnyTwoEvents": {
Expand Down Expand Up @@ -103,7 +104,8 @@
"txHash": "3f81b00a78830bb0186539cceed5ac137aad0d6872dd998c533c2758fbda0a6c"
}
],
"latestLedger": 1197964
"latestLedger": 1197964,
"cursor": "0005111084096696320-0000000001"
}
}
}
4 changes: 2 additions & 2 deletions openrpc/src/stellar-rpc/methods/getEvents.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
"$ref": "#/components/contentDescriptors/EventFilters"
},
{
"$ref": "#/components/contentDescriptors/EventsPagination"
"$ref": "#/components/contentDescriptors/Pagination"
},
{
"$ref": "#/components/contentDescriptors/Format"
Expand All @@ -39,7 +39,7 @@
},
"cursor": {
"type": "string",
"$ref": "#/components/schemas/GetEventsCursor"
"$ref": "#/components/schemas/Cursor"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each event itself also has a cursor - I think that needs to be updated, too?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in the event schema the field is still called pagingToken:

https://github.com/stellar/stellar-rpc/blob/main/protocol/get_events.go#L29-L30

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh oof, gotcha. That one is still useful for mid-page eventing, though, so idk if deprecated is the word? Then again they should use id for that.

}
}
}
Expand Down
6 changes: 5 additions & 1 deletion openrpc/src/stellar-rpc/methods/getLedgers.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"$ref": "#/components/contentDescriptors/StartLedger"
},
{
"$ref": "#/components/contentDescriptors/TransactionsPagination"
"$ref": "#/components/contentDescriptors/Pagination"
},
{
"$ref": "#/components/contentDescriptors/Format"
Expand Down Expand Up @@ -39,6 +39,10 @@
},
"oldestLedgerCloseTime": {
"$ref": "#/components/schemas/OldestLedgerCloseTime"
},
"cursor": {
"type": "string",
"$ref": "#/components/schemas/Cursor"
}
}
}
Expand Down
6 changes: 5 additions & 1 deletion openrpc/src/stellar-rpc/methods/getTransactions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"$ref": "#/components/contentDescriptors/StartLedger"
},
{
"$ref": "#/components/contentDescriptors/TransactionsPagination"
"$ref": "#/components/contentDescriptors/Pagination"
},
{
"$ref": "#/components/contentDescriptors/Format"
Expand Down Expand Up @@ -39,6 +39,10 @@
},
"oldestLedgerCloseTimestamp": {
"$ref": "#/components/schemas/OldestLedgerCloseTime"
},
"cursor": {
"type": "string",
"$ref": "#/components/schemas/Cursor"
}
}
}
Expand Down
7 changes: 1 addition & 6 deletions openrpc/src/stellar-rpc/schemas/Cursor.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."
}
}
2 changes: 1 addition & 1 deletion openrpc/src/stellar-rpc/schemas/Event.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down
18 changes: 3 additions & 15 deletions openrpc/src/stellar-rpc/schemas/Pagination.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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": []
}
}
39 changes: 24 additions & 15 deletions static/stellar-rpc.openrpc.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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."
}
}
}
Expand Down Expand Up @@ -301,7 +300,8 @@
"txHash": "3fa1787085a4aa585507751394d70494a02e71d347446095a763ecbfc647937c"
}
],
"latestLedger": 1197926
"latestLedger": 1197926,
"cursor": "0005121482212511744-0000000002"
}
}
},
Expand Down Expand Up @@ -356,7 +356,8 @@
"txHash": "3f81b00a78830bb0186539cceed5ac137aad0d6872dd998c533c2758fbda0a6c"
}
],
"latestLedger": 1197964
"latestLedger": 1197964,
"cursor": "0005111084096696320-0000000001"
}
}
}
Expand Down Expand Up @@ -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."
}
}
}
Expand Down Expand Up @@ -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."
}
}
}
Expand Down Expand Up @@ -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."
}
}
}
Expand Down Expand Up @@ -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."
}
}
}
Expand Down