53 lines
1.5 KiB
ReStructuredText
53 lines
1.5 KiB
ReStructuredText
.. _pagination:
|
|
|
|
Paginated APIs
|
|
==============
|
|
|
|
Some APIs in Sachet might return lots of data.
|
|
Because this is often a lot to handle, Sachet will use pagination on some endpoints.
|
|
|
|
For example, let's say we want to list all shares on the server.
|
|
|
|
To do this, we'll run ``GET /files?page=1&per_page=3``.
|
|
|
|
Paginated APIs on Sachet require the following parameters:
|
|
|
|
* ``page`` : the number of the page we want to query;
|
|
* ``per_page`` : the number of items per page we receive.
|
|
|
|
For our example, the server might respond like this (fields removed for brevity):
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"data": [
|
|
{
|
|
"file_name": "file1",
|
|
"share_id": "339ce639-cf54-4acf-9620-c915c5dce406"
|
|
},
|
|
{
|
|
"file_name": "file2",
|
|
"share_id": "9ae90f06-a751-409c-a9fe-8277575b9914"
|
|
},
|
|
{
|
|
"file_name": "file3",
|
|
"share_id": "4f8e41ab-3327-4fc1-a52b-8951ac5c641f"
|
|
}
|
|
],
|
|
"next": 2,
|
|
"pages": 3,
|
|
"prev": null
|
|
}
|
|
|
|
Our query's result is returned as an array in ``data``.
|
|
As we requested, we have 3 items on the first page.
|
|
|
|
There's also two extra fields ``next`` and ``prev``,
|
|
which help us navigate to other pages.
|
|
Since we're on the first page, there is no previous page, which is why ``prev`` is empty.
|
|
|
|
If we wished to go to the next page, we'd make the same request with the new page number.
|
|
|
|
The ``pages`` field is the total number of pages there is in this query.
|
|
That is, page 3 is the last page in this example.
|