Add configurable pagination query parameter names.

Author: n2ygk

docs/usage.md

@@ -34,14 +34,65 @@ REST_FRAMEWORK = {
 }
 ```
 
-If `PAGE_SIZE` is set the renderer will return a `meta` object with
+### Pagination settings
+
+If `REST_FRAMEWORK['PAGE_SIZE']` is set the renderer will return a `meta` object with
 record count and a `links` object with the next, previous, first, and last links.
-Pages can be selected with the `page` GET parameter. The query parameter used to
-retrieve the page can be customized by subclassing `PageNumberPagination` and
-overriding the `page_query_param`.  Page size can be controlled per request via
-the `PAGINATE_BY_PARAM` query parameter (`page_size` by default).
 
-#### Performance Testing
+#### Subclassing paginators
+
+The JSON API pagination classes can be subclassed to override settings as
+described in the [DRF pagination documentation](http://www.django-rest-framework.org/api-guide/pagination/).
+
+The default values are shown in these examples:
+
+```python
+from rest_framework_json_api.pagination import PageNumberPagination, LimitOffsetPagination
+
+class MyPagePagination(PageNumberPagination):
+    page_query_param = 'page'
+    page_size_query_param = 'page_size'
+    max_page_size = 100
+
+class MyLimitPagination(LimitOffsetPagination):
+    offset_query_param = 'page[offset]'
+    limit_query_param = 'page[limit]'
+    max_limit = None
+```
+
+As shown above, pages can be selected with the `page` or `page[limit]` GET query parameter when using
+the PageNumberPagination or LimitOffsetPagination class, respectively. 
+
+If you want to use the PageNumberPagination query parameter names shown
+as an example in the JSON API [specification](http://jsonapi.org/format/#fetching-pagination),
+set them as follows:
+```python
+class MyPagePagination(PageNumberPagination):
+    page_query_param = 'page[number]'
+    page_size_query_param = 'page[size]'
+```
+
+#### Setting global defaults for pagination
+
+Set global defaults for the `PageNumberPagination` class with these settings:
+- `JSON_API_PAGE_NUMBER_PARAM` sets the name of the page number query parameter (default: "page").
+- `JSON_API_PAGE_SIZE_PARAM` sets the name of the page size query parameter (default: "page_size").
+- `JSON_API_MAX_PAGE_SIZE` sets an upper limit for the page size query parameter (default: 100).
+
+Set global defaults for the `LimitOffsetPagination` class with these settings:
+- `JSON_API_PAGE_OFFSET_PARAM` sets the name of the page offset query parameter (default: "page\[offset\]").
+- `JSON_API_PAGE_LIMIT_PARAM` sets the name of the page limit query parameter (default: "page\[limit\]").
+- `JSON_API_MAX_PAGE_LIMIT` sets an upper limit for the page limit query parameter (default: None).
+
+If you want to set the default PageNumberPagination query parameter names shown
+as an example in the JSON API [specification](http://jsonapi.org/format/#fetching-pagination),
+set them as follows:
+```python
+JSON_API_PAGE_NUMBER_PARAM = 'page[number]'
+JSON_API_PAGE_SIZE_PARAM = 'page[size]'
+```
+
+### Performance Testing
 
 If you are trying to see if your viewsets are configured properly to optimize performance,
 it is preferable to use `example.utils.BrowsableAPIRendererWithoutForms` instead of the default `BrowsableAPIRenderer`
@@ -606,6 +657,7 @@ with 1e18 rows which will likely exhaust any available memory and
 slow your database to crawl.
 
 The prefetch_related case will issue 4 queries, but they will be small and fast queries.
+
 <!--
 ### Relationships
 ### Errors

rest_framework_json_api/pagination.py

@@ -3,6 +3,7 @@
 """
 from collections import OrderedDict
 
+from django.conf import settings
 from rest_framework.pagination import LimitOffsetPagination, PageNumberPagination
 from rest_framework.utils.urls import remove_query_param, replace_query_param
 from rest_framework.views import Response
@@ -11,10 +12,12 @@
 class PageNumberPagination(PageNumberPagination):
     """
     A json-api compatible pagination format
+    TODO: Consider changing defaults to page[number] and page[size].
+      This would be a breaking change.
     """
-
-    page_size_query_param = 'page_size'
-    max_page_size = 100
+    page_query_param = getattr(settings, 'JSON_API_PAGE_NUMBER_PARAM', 'page')
+    page_size_query_param = getattr(settings, 'JSON_API_PAGE_SIZE_PARAM', 'page_size')
+    max_page_size = getattr(settings, 'JSON_API_MAX_PAGE_SIZE', 100)
 
     def build_link(self, index):
         if not index:
@@ -55,8 +58,10 @@ class LimitOffsetPagination(LimitOffsetPagination):
     http://api.example.org/accounts/?page[limit]=100
     http://api.example.org/accounts/?page[offset]=400&page[limit]=100
     """
-    limit_query_param = 'page[limit]'
-    offset_query_param = 'page[offset]'
+    limit_query_param = getattr(settings, 'JSON_API_PAGE_LIMIT_PARAM', 'page[limit]')
+    offset_query_param = getattr(settings, 'JSON_API_PAGE_OFFSET_PARM', 'page[offset]')
+    # TODO: inconsistent w/max_page_size value default of 100
+    max_limit = getattr(settings, 'JSON_API_MAX_PAGE_LIMIT', None)
 
     def get_last_link(self):
         if self.count == 0:
@@ -96,3 +101,5 @@ def get_paginated_response(self, data):
                 ('prev', self.get_previous_link())
             ])
         })
+
+# TODO: Add CursorPagination