Docs for `MAX_PAGINATE_BY` setting & view attribute.

2 files changed, 34 insertions, 3 deletions

diff --git a/docs/api-guide/pagination.md b/docs/api-guide/pagination.md
index ca0174b7..0829589f 100644
--- a/docs/api-guide/pagination.md
+++ b/docs/api-guide/pagination.md
@@ -85,11 +85,12 @@ We could now use our pagination serializer in a view like this.
 
 The generic class based views `ListAPIView` and `ListCreateAPIView` provide pagination of the returned querysets by default.  You can customise this behaviour by altering the pagination style, by modifying the default number of results, by allowing clients to override the page size using a query parameter, or by turning pagination off completely.
 
-The default pagination style may be set globally, using the `DEFAULT_PAGINATION_SERIALIZER_CLASS`, `PAGINATE_BY` and `PAGINATE_BY_PARAM` settings.  For example.
+The default pagination style may be set globally, using the `DEFAULT_PAGINATION_SERIALIZER_CLASS`, `PAGINATE_BY`, `PAGINATE_BY_PARAM`, and `MAX_PAGINATE_BY` settings.  For example.
 
     REST_FRAMEWORK = {
-        'PAGINATE_BY': 10,
-        'PAGINATE_BY_PARAM': 'page_size' 
+        'PAGINATE_BY': 10,                 # Default to 10
+        'PAGINATE_BY_PARAM': 'page_size',  # Allow client to override, using `?page_size=xxx`.
+        'MAX_PAGINATE_BY': 100             # Maximum limit allowed when using `?page_size=xxx`.
     }
 
 You can also set the pagination style on a per-view basis, using the `ListAPIView` generic class-based view.
@@ -99,6 +100,7 @@ You can also set the pagination style on a per-view basis, using the `ListAPIVie
         serializer_class = ExampleModelSerializer
         paginate_by = 10
         paginate_by_param = 'page_size'
+        max_paginate_by = 100
 
 Note that using a `paginate_by` value of `None` will turn off pagination for the view.
 
diff --git a/docs/api-guide/settings.md b/docs/api-guide/settings.md
index fe7925a5..542e8c5f 100644
--- a/docs/api-guide/settings.md
+++ b/docs/api-guide/settings.md
@@ -127,6 +127,35 @@ Default: `None`
 
 The name of a query parameter, which can be used by the client to override the default page size to use for pagination.  If set to `None`, clients may not override the default page size.
 
+For example, given the following settings:
+
+    REST_FRAMEWORK = {
+    	'PAGINATE_BY': 10,
+    	'PAGINATE_BY_PARAM': 'page_size',
+    }
+
+A client would be able to modify the pagination size by using the `page_size` query parameter.  For example:
+
+    GET http://example.com/api/accounts?page_size=25
+
+Default: `None`
+
+#### MAX_PAGINATE_BY
+
+The maximum page size to allow when the page size is specified by the client.  If set to `None`, then no maximum limit is applied.
+
+For example, given the following settings:
+
+    REST_FRAMEWORK = {
+    	'PAGINATE_BY': 10,
+    	'PAGINATE_BY_PARAM': 'page_size',
+        'MAX_PAGINATE_BY': 100
+    }
+
+A client request like the following would return a paginated list of up to 100 items.
+
+    GET http://example.com/api/accounts?page_size=999
+
 Default: `None`
 
 ---