feat(api): add pagination page for v2 api#1868
Conversation
laviniat1996
added
the
scope: api
This comment has been minimized.
This comment has been minimized.
|
/review |
|
@reveloper So I added parameters here as well for each endpoint, the params are already listed in the autogenerated api pages section. Should we keep them here as well or not? I'm not sure |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| --- | ||
| title: "Pagination" | ||
| sidebarTitle: "Pagination" | ||
| --- |
There was a problem hiding this comment.
[HIGH] Title and sidebarTitle use non-descriptive single-word heading
The frontmatter sets title and sidebarTitle to the single word "Pagination", which does not clearly describe the page as TON Center v2 pagination guidance. The extended docs style encourages descriptive, sentence‑case headings that explain what the page covers rather than bare nouns, to improve navigation and searchability. The current heading also misses an opportunity to distinguish this page from other pagination references elsewhere in the docs.
| --- | |
| title: "Pagination" | |
| sidebarTitle: "Pagination" | |
| --- | |
| --- | |
| title: "Pagination in v2 API" | |
| sidebarTitle: "Pagination" | |
| --- |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| | Endpoint | Cursor parameters | End of results signal | | ||
| | -------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------- | | ||
| | [`getTransactions`](/ecosystem/api/toncenter/v2/accounts/list-account-transactions) | `lt` + `hash` | Response returns fewer results than `limit` | | ||
| | [`getBlockTransactions`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions) | `after_lt` + `after_hash` | `incomplete` field is `false` | | ||
| | [`getBlockTransactionsExt`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions-extended-details) | `after_lt` + `after_hash` | `incomplete` field is `false` | |
There was a problem hiding this comment.
[HIGH] Cursor parameter combinations use + inside code spans instead of prose
In the “Cursor parameters” column, the cursor pairs are written as `lt` + `hash` and `after_lt` + `after_hash`, rendering the plus sign inside code spans. This makes + look like part of the code expression rather than just a way of describing that the two parameters are used together. The style guidance prefers reserving code spans for actual identifiers and literals, and using plain punctuation or wording outside code when joining separate tokens.
| | Endpoint | Cursor parameters | End of results signal | | |
| | -------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------- | | |
| | [`getTransactions`](/ecosystem/api/toncenter/v2/accounts/list-account-transactions) | `lt` + `hash` | Response returns fewer results than `limit` | | |
| | [`getBlockTransactions`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions) | `after_lt` + `after_hash` | `incomplete` field is `false` | | |
| | [`getBlockTransactionsExt`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions-extended-details) | `after_lt` + `after_hash` | `incomplete` field is `false` | | |
| | Endpoint | Cursor parameters | End of results signal | | |
| | -------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------- | | |
| | [`getTransactions`](/ecosystem/api/toncenter/v2/accounts/list-account-transactions) | `lt` and `hash` | Response returns fewer results than `limit` | | |
| | [`getBlockTransactions`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions) | `after_lt` and `after_hash` | `incomplete` field is `false` | | |
| | [`getBlockTransactionsExt`](/ecosystem/api/toncenter/v2/blocks/list-block-transactions-extended-details) | `after_lt` and `after_hash` | `incomplete` field is `false` | |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| Transaction hashes are base64-encoded and may contain `+`, `/`, and `=` characters. These must be URL-encoded when passed as query parameters: `+` → `%2B`, `/` → `%2F`, `=` → `%3D`. Most HTTP libraries handle this automatically, but this is important when constructing URLs manually. | ||
| </Aside> | ||
|
|
||
| ## getTransactions |
There was a problem hiding this comment.
[HIGH] Endpoint section headings not in sentence case
The endpoint section heading at line 27 is written as the raw identifier getTransactions instead of a sentence‑case title like “Get transactions”. This violates the documentation style rule that headings must use sentence case (capitalize only the first word and proper nouns), as defined in https://github.com/ton-org/docs/blob/main/contribute/style-guide-extended.mdx?plain=1#L441-L453. The same issue appears for the later endpoint sections ## getBlockTransactions and ## getBlockTransactionsExt in this file. Keeping headings in sentence case improves consistency and readability across the docs while preserving the exact endpoint names in the body text.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```bash | ||
| curl "https://toncenter.com/api/v2/getTransactions?address=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=5" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
[HIGH] First getTransactions curl example inlines literal address and limit without placeholders
The first curl example for getTransactions embeds a specific account address and limit=5 directly in a copy‑pasteable command. The docs style requires using <ANGLE_CASE> placeholders for values that readers must replace (such as addresses and limits) to avoid accidental reuse of opaque sample values. Leaving real‑looking values in runnable commands increases copy/paste risk and hides which parts of the URL are meant to be customized.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```bash | ||
| curl "https://toncenter.com/api/v2/getTransactions?address=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=5<=66784070000010&hash=jYTMpoesWRQ9gs9sbiYcRu%2BraNOU1Jd3bqCC9V%2FntFU%3D" | ||
| ``` |
There was a problem hiding this comment.
[HIGH] Follow-up getTransactions curl example repeats literal address instead of placeholders
The second curl example in the pagination steps also hard‑codes the same account address and limit as the first example. This is inconsistent with the placeholder pattern recommended for user‑provided values and makes it less obvious that the address and limit must be updated in real usage. Maintaining the real cursor values here is useful, but the reusable parameters should still use placeholders for clarity and safety.
| ```bash | |
| curl "https://toncenter.com/api/v2/getTransactions?address=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=5<=66784070000010&hash=jYTMpoesWRQ9gs9sbiYcRu%2BraNOU1Jd3bqCC9V%2FntFU%3D" | |
| ``` | |
| ```bash | |
| curl "https://toncenter.com/api/v2/getTransactions?address=<ACCOUNT_ADDR>&limit=<LIMIT><=66784070000010&hash=jYTMpoesWRQ9gs9sbiYcRu%2BraNOU1Jd3bqCC9V%2FntFU%3D" | |
| ``` |
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| const address = "EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2"; | ||
|
|
There was a problem hiding this comment.
[HIGH] JavaScript pagination script uses concrete address instead of a placeholder
In the “Full pagination script” for getTransactions, the script defines const address using a specific account address with no indication that it is an example value. For code that readers may copy into their own projects, the docs style expects user‑supplied values to be expressed via clear placeholders or named constants, so it is obvious what must be changed. Leaving the literal address in the script encourages reuse of that exact value and obscures the need to substitute a real account.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| ```bash | ||
| curl "https://toncenter.com/api/v2/getTransactions?address=EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2&limit=20<=66822814000007&to_lt=66784070000010" | ||
| ``` | ||
|
|
||
| This returns transactions between the two logical times, which is useful when syncing only recent activity. |
There was a problem hiding this comment.
[HIGH] Fetching a specific range example lacks placeholders for adjustable values
The Fetching a specific range section presents a runnable curl command that hard‑codes a concrete address, limit, and logical times without any placeholders. As with earlier examples, these are values the reader is expected to change, and the style guide prefers angle‑bracket placeholders to make such customization obvious. Reusing fully literal values for addresses and pagination bounds in commands makes it too easy to copy them directly without understanding their meaning.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
| "account": "-1:3333333333333333333333333333333333333333333333333333333333333333", | ||
| "lt": "67098924000001", | ||
| "hash": "4HIgukW2DrYLGAm8fviPr83e/pNuY3Ys4kLwt+93248=" | ||
| }, | ||
| { | ||
| "@type": "blocks.shortTxId", | ||
| "account": "-1:3333333333333333333333333333333333333333333333333333333333333333", | ||
| "lt": "67098924000002", | ||
| "hash": "dveSZ4S5kWt+gi32AEdDW5X5ie3U36gQW+Gls1ZjOVg=" | ||
| }, | ||
| { | ||
| "@type": "blocks.shortTxId", | ||
| "account": "-1:3333333333333333333333333333333333333333333333333333333333333333", |
There was a problem hiding this comment.
[HIGH] Example block transaction outputs expose realistic-looking account identifiers without marking them as samples
In the getBlockTransactions example response, the account field is populated with a full account ID -1:3333…3333 that appears as a live‑format identifier, and later examples show similarly structured addresses. For safety‑sensitive blockchain documentation, addresses and keys in examples should be clearly marked as placeholders or test/sample values to avoid users copying them into production workflows. Presenting realistic‑looking values without such labeling can mislead readers into thinking they are safe to reuse verbatim.
Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!
1 participant
closes #1024
This PR adds a new page which contains in-depth details about how API v2 pagination works.