API: Pagination

From Yombo
Jump to: navigation, search

Overview

See also

Some result sets might be rather large and may be hard for low powered devices to handle all at one. Pagination and record set size is fully controllable through query string arguments.

Syntax

Pagination is controlled through the page query string parameter. This parameter has the following sub-selections. Eg: ?page[size]=3

  • size - How many records to return.
  • number - What page to return.

For example, if there are a total of 8 records, and the request size is set to 2, there will be 4 pages or results.

The results always include two sections called 'meta' and 'links'. This will provide you information of the total number of records, the current page being returned, links to get the previous, next, last, and first page, as well as other details.

Examples

Get 2 commands at a time, get the first page of results - records 1 and 2.

  • GET /api/v1/commands?page[size]=2&page[number]=1
    • This will return records 1 and 2.
  • GET /api/v1/commands?page[size]=2&page[number]=3
    • This will return records 5 and 6.
  <div id="curl<random_number></random_number>" class="tab-pane fade in active" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
curl \
-H "x-api-key: abc123xyz789" \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...." \
-H "Accept: application/json" \
https://api.yombo.net/api/v1/commands?page[number]=2&page[size]=3
  <div id="python<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
import requests

url = 'https://api.yombo.net/api/v1/commands?page[number]=2&page[size]=3'
headers = {
    'x-api-key': 'abc123xyz789',
    'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJ...',
    'Accept': 'application/json',  # demo, this is the default
    }
response = requests.get(url, headers=headers)
the_data = response.json()  # create a dictionary from results
  <div id="output<random_number></random_number>" class="tab-pane fade" style="border: 1px solid #ccc; border-radius: 5px; padding: 0.7em;">
 1 {
 2     "data": [
 3         {
 4             "type": "commands",
 5             "id": "QrpzPqKwNjSmqLw7O",
 6             "attributes": {
 7                 "id": "QrpzPqKwNjSmqLw7O",
 8                 "voice_cmd": "open",
 9                 "machine_label": "open",
10                 "label": "Open",
11                 "description": "Sends an open command",
12                 "public": 2,
13                 "status": 1,
14                 "created_at": 1482065387,
15                 "updated_at": 1482065387
16             },
17             "links": {
18                 "self": "https://api.yombo.net/api/v1/commands/QrpzPqKwNjSmqLw7O"
19             }
20         },
21         {
22             "type": "commands",
23             "id": "QrpzPqK5W9CxoLw7O",
24             "attributes": {
25                 "id": "QrpzPqK5W9CxoLw7O",
26                 "voice_cmd": "dim",
27                 "machine_label": "dim",
28                 "label": "Dim",
29                 "description": "Sends a dim command",
30                 "public": 2,
31                 "status": 1,
32                 "created_at": 1482065387,
33                 "updated_at": 1482065387
34             },
35             "links": {
36                 "self": "https://api.yombo.net/api/v1/commands/QrpzPqK5W9CxoLw7O"
37             }
38         },
39         {
40             "type": "commands",
41             "id": "ZdMbq7kGzmcmqWyPp",
42             "attributes": {
43                 "id": "ZdMbq7kGzmcmqWyPp",
44                 "voice_cmd": "brighten",
45                 "machine_label": "brighten",
46                 "label": "Brighten",
47                 "description": "Sends a brighten command",
48                 "public": 2,
49                 "status": 1,
50                 "created_at": 1482065387,
51                 "updated_at": 1482065387
52             },
53             "links": {
54                 "self": "https://api.yombo.net/api/v1/commands/ZdMbq7kGzmcmqWyPp"
55             }
56         }
57     ],
58     "meta": {
59         "count": 3,
60         "current_page": 2,
61         "from": 4,
62         "last_page": 12,
63         "path": "https://api.yombo.net/api/v1/commands",
64         "per_page": 3,
65         "to": 6,
66         "total": 35,
67         "includable": [
68             "users"
69         ]
70     },
71     "links": {
72         "first": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=1",
73         "last": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=12",
74         "prev": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=1",
75         "next": "https://api.yombo.net/api/v1/commands?page%5Bsize%5D=3&page%5Bnumber%5D=3",
76         "self": "https://api.yombo.net/api/v1/commands"
77     }
78 }
This page was last edited on 11 April 2019.