Document need pagination (fixes #81)

GitHub-Pull-Request: https://github.com/syncthing/docs/pull/172

rest/db-need-get.rst

@@ -1,9 +1,28 @@
 GET /rest/db/need
 =================
 
-Takes one parameter, ``folder``, and returns lists of files which are
+Takes one mandatory parameter, ``folder``, and returns lists of files which are
 needed by this device in order for it to become in sync.
 
+Furthermore takes an optional ``page`` and ``perpage`` arguments for pagination.
+Pagination happens, across the union of all needed files, that is - across all
+3 sections of the response.
+For example, given the current need state is as follows:
+
+1. ``progress`` has 15 items
+2. ``queued`` has 3 items
+3. ``rest`` has 12 items
+
+If you issue a query with ``page=1`` and ``perpage=10``, only the ``progress``
+section in the response will have 10 items. If you issue a request query with
+``page=2`` and ``perpage=10``, ``progress`` section will have the last 5 items,
+``queued`` section will have all 3 items, and ``rest`` section will have first
+2 items. If you issue a query for ``page=3`` and ``perpage=10``, you will only
+have the last 10 items of the ``rest`` section.
+
+In all these calls, ``total`` will be 30 to indicate the total number of
+available items.
+
 .. code-block:: bash
 
     {
@@ -28,7 +47,10 @@ needed by this device in order for it to become in sync.
       # This happens when we start downloading files, and new files get added while we are downloading.
       "rest": [
           ...
-      ]
+      ],
+      "page": 1,
+      "perpage": 100,
+      "total": 2000
     }
 
 .. note::