From 4a55ad7ac0aea9bfa4047d3ae4cd731f2b4501a6 Mon Sep 17 00:00:00 2001
From: dogeystamp <dogeystamp@disroot.org>
Date: Sat, 20 May 2023 20:06:35 -0400
Subject: [PATCH] docs/pagination.rst: added

---
 docs/index.rst      |  1 +
 docs/pagination.rst | 52 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 53 insertions(+)
 create mode 100644 docs/pagination.rst

diff --git a/docs/index.rst b/docs/index.rst
index 3fb9515..36eb376 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,6 +11,7 @@ Welcome to Sachet's documentation!
    :caption: Contents:
 
    authentication
+   pagination
    permissions
    user
    admin
diff --git a/docs/pagination.rst b/docs/pagination.rst
new file mode 100644
index 0000000..29cbc4d
--- /dev/null
+++ b/docs/pagination.rst
@@ -0,0 +1,52 @@
+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`` using the following request body:
+
+.. code-block:: json
+
+    {
+        "page": "1",
+        "per_page": "3"
+    }
+
+As seen in the above example, 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,
+       "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.