Add pagination info to docs

docs/rest-api.yml

@@ -93,6 +93,22 @@ paths:
             inactive: all users who have *no* active servers (complement of active)
 
             Added in JupyterHub 1.3
+        - name: offset
+          in: query
+          required: false
+          type: number
+          description: |
+            Return a number users starting at the given offset.
+            Can be used with limit to paginate.
+            If unspecified, return all users.
+        - name: limit
+          in: query
+          requred: false
+          type: number
+          description: |
+            Return a finite number of users.
+            Can be used with offset to paginate.
+            If unspecified, return all users.
       responses:
         "200":
           description: The Hub's user list
@@ -423,6 +439,23 @@ paths:
   /groups:
     get:
       summary: List groups
+      parameters:
+        - name: offset
+          in: query
+          required: false
+          type: number
+          description: |
+            Return a number of groups starting at the specified offset.
+            Can be used with limit to paginate.
+            If unspecified, return all groups.
+        - name: limit
+          in: query
+          required: false
+          type: number
+          description: |
+            Return a finite number of groups.
+            Can be used with offset to paginate.
+            If unspecified, return all groups.
       responses:
         "200":
           description: The list of groups
@@ -439,6 +472,22 @@ paths:
           in: path
           required: true
           type: string
+        - name: offset
+          in: query
+          required: false
+          type: number
+          description: |
+            Return a number of users within the given group starting at the specified offset.
+            Can be used with limit to paginate.
+            If unspecified, return all group users.
+        - name: limit
+          in: query
+          required: false
+          type: number
+          description: |
+            Return a finite number of users within the given group.
+            Can be used with offset to paginate.
+            If unspecified, return all users.
       responses:
         "200":
           description: The group model
@@ -545,6 +594,23 @@ paths:
     get:
       summary: Get the proxy's routing table
       description: A convenience alias for getting the routing table directly from the proxy
+      parameters:
+        - name: offset
+          in: query
+          required: false
+          type: number
+          description: |
+            Return a number of routes starting at the given offset.
+            Can be used with limit to paginate.
+            If unspecified, return all routes.
+        - name: limit
+          in: query
+          requred: false
+          type: number
+          description: |
+            Return a finite number of routes.
+            Can be used with offset to paginate.
+            If unspecified, return all routes.
       responses:
         "200":
           description: Routing table

docs/source/reference/rest.md

@@ -158,6 +158,25 @@ provided by notebook servers managed by JupyterHub if one of the following is tr
 1. The token is for the same user as the owner of the notebook
 2. The token is tied to an admin user or service **and** `c.JupyterHub.admin_access` is set to `True`
 
+## Paginating API requests
+
+Pagination is available through the `offset` and `limit` query parameters on
+certain endpoints, which can be used to return ideally sized windows of results.
+Here's example code demonstrating pagination on the `GET /users`
+endpoint to fetch the first 20 records.
+
+```python
+import requests
+
+api_url = 'http://127.0.0.1:8081/hub/api'
+
+r = requests.get(api_url + '/users?offset=0&limit=20')
+r.raise_for_status()
+r.json()
+```
+
+Pagination is enabled on the `GET /users`, `GET /groups`, `GET /groups/{name}`, and `GET /proxy` REST endpoints.
+
 ## Enabling users to spawn multiple named-servers via the API
 
 With JupyterHub version 0.8, support for multiple servers per user has landed.