Upcoming Changes to API Pagination

For everyone building tooling atop our Beta API, we have some upcoming changes to announce! 

Here is the quick summary:

• To improve the API’s performance we are changing how pagination works
• The new cursor-based pagination is available starting today. Docs are here.
• Our old pagination scheme will continue to work until Friday Nov 6th, 2020. Make sure you update anything that uses the old pagination by then.
• If you have any issues with the new pagination, please let us know via Intercom or support@kolide.co right away.

New Pagination Details

In an effort to improve performance, we’re changing our pagination strategy for API endpoints that return collections of results. 

Complete details and the documentation can be found at the link included at the bottom of this post, but the condensed version is: We’re moving from simple page-number-based pagination to cursor-based pagination. This means that instead of making requests like this:

curl --request GET \
  --url "https://k2.kolide.com/api/v0/audit_logs?page=2&per_page=25" \
  --header 'accept: application/json'

# ->
#{
# page: 2,
# last_page: 3,
# data: [
# {...}
# ]
#}

in the future, you’ll make API requests using a cursor= query parameter to specify pages of data past the first page: 

curl --request GET \
  --url "https://k2.kolide.com/api/v0/audit_logs?per_page=25&cursor=" \
  --header 'accept: application/json'

# ->
# {
# pagination: {
# next: "https://k2.kolide.com/api/v0/audit_logs?per_page=25&cursor=ABCDJ",
# next_cursor: "ABCDJ",
# current_cursor: "JDCBA",
# count: 25,
# }
# data: [...]
#}

Because no one likes to re-write their tools while worrying about downtime, we are doing a staged roll-out. The API currently behaves as it always has with respect to pagination: if you supply a page= query parameter, or only specify search and per_page, the API will use and respond with the existing page-number-based pagination. The original pagination scheme will continue to work until Friday Nov 6th, 2020. Make sure you update anything that uses the old pagination by then.

However, if you specify a cursor= query parameter (even a blank one, see the examples above), the API will use cursor-based pagination, and will respond with the new pagination information described above. This means that you can update your API clients to prepare for the coming updates, without worrying that your existing workflows and automation will be broken while you feverishly re-write them.

For full documentation and details, see https://kolidek2.readme.io/docs/pagination.