Merge pull request #8 from TrueBlocks/feature/new_paging_docs

Updated docs: new pagination, tb_getBounds

content/english/_index.md

@@ -6,7 +6,7 @@ banner:
   button:
     enable: true
     label: "Try on QuickNode Marketplace"
-    link: ""
+    link: "https://marketplace.quicknode.com/add-on/trueblocks-key"
 
 # Features
 features:

content/english/docs/appearance.md

@@ -19,15 +19,14 @@ Returns appearances of the given address.
 ```javascript
 "params": [{
   "address": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5",
-  "page": 1,
   "perPage": 100
 }]
 ```
 
 1. `Object`
     - `address`: Address - address for which to return the appearances
-    - `page`: Uint - (optional) data page to return
     - `perPage`: Uint - (optional) number of items per page
+    - `pageId`: PageId - (optional) page to return. See [Pagination](#pagination).
 
 ### Returns
 
@@ -59,15 +58,17 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"tb_getAppearances","params":[{se
     ],
     "meta": {
       "lastIndexedBlock": 19268245,
-      "address": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
+      "address": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5",
+      "previousPageId": "QVl3ZUp3SEJRTzBBZVFBQUFIaXFJQUVRQVFBQWlKVUJBSitHQVFBPQ==",
+      "nextPageId": null
     }
   }
 }
 ```
 
-## `tb_getAppearanceCount` method
+## `tb_getBounds` method
 
-Returns number of appearances of the given address.
+Returns the latest and earliest appearance for the given address.
 
 ### Parameters
 
@@ -83,22 +84,33 @@ Returns number of appearances of the given address.
 
 ### Returns
 
-Number (decimal) of appearances
+`Bounds` object with exactly 2 appearances.
 
 ### Example
 
 ```bash
 # Request
-curl -X POST --data '{"jsonrpc":"2.0","method":"tb_getAppearanceCount","params":[{see above}],"id":1}'
+curl -X POST --data '{"jsonrpc":"2.0","method":"tb_getBounds","params":[{see above}],"id":1}'
 # Result
 {
   "id": 1,
   "jsonrpc": "2.0",
   "result": {
-    "data": 5302,
+    "data": {
+      "latest": {
+        "blockNumber": 19325230,
+        "transactionIndex": 17
+      },
+      "earliest": {
+        "blockNumber": 8854723,
+        "transactionIndex": 61
+      }
+    },
     "meta": {
       "lastIndexedBlock": 19268245,
-      "address": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5"
+      "address": "0x52bc44d5378309ee2abf1539bf71de1b7d7be3b5",
+      "previousPageId": null,
+      "nextPageId": null
     }
   }
 }
@@ -133,3 +145,20 @@ curl -X POST --data '{"jsonrpc":"2.0","method":"tb_status","params":[],"id":1}'
   }
 }
 ```
+
+## Pagination
+
+The API uses _keyset pagination model_. It means that there are ids of next and previous page attached to every response, in its `meta` section:
+```json
+{
+  "meta": {
+    "previousPageId": "QVl3ZUp3RzRRTzBBOWdBQUFIaXFJQUVRQVFBQWlKVUJBSitHQVFBPQ==",
+    "nextPageId": "QUl3ZUp3SEJRTzBBZUFBQUFIaXFJQUVRQVFBQWlKVUJBSitHQVFBPQ=="
+  }
+}
+```
+To fetch another page, you have to set `pageId` in your request to one of the returned ids.
+If there is no previous page, `previousPageId` will be `null`. Similarly, the request for the latest page will return `null` as  `nextPageId`.
+
+If `pageId` is not set, the API returns the **latest** page.
+You can set `pageId` to `"earliest"` to fetch the earliest page.