djangorestframework-link-header-pagination

Overview

Provide pagination using a Link HTTP header as described in GitHub's REST API documentation.

This pagination style accepts a single page number in the request query parameters. The response uses an HTTP header called Link to provide the URLs for the next, previous, first, and last pages. If you are using Python's Requests library to make the request, this header is automatically parsed for you as described here.

Request:

GET https://api.example.org/accounts/?page=4

Response:

HTTP 200 OK
Link: <https://api.example.org/accounts/>; rel="first", <https://api.example.org/accounts/?page=3>; rel="prev", <https://api.example.org/accounts/?page=5>; rel="next", <https://api.example.org/accounts/?page=11>; rel="last"

[
   {
       "id": 1,
       "name": "item one",
   },
   ...
]

Requirements

• Python (3.7+)
• Django (3.2+)
• Django REST Framework (3.11+)

Installation

Install using pip:

$ pip install djangorestframework-link-header-pagination

Setup

Add drf_link_header_pagination to your project's INSTALLED_APPS setting.

To enable the LinkHeaderPagination style globally, use the following configuration, modifying the PAGE_SIZE as desired:

REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'drf_link_header_pagination.LinkHeaderPagination',
    'PAGE_SIZE': 100
}

On GenericAPIView subclasses you may also set the pagination_class attribute to select LinkHeaderPagination on a per-view basis.

Other pagination classes that are available are:

• LinkHeaderCursorPagination: This is similar to the normal CursorPagination class but using the Link header to return only the next and/or prev links. The first and last links are unavailable.
• LinkHeaderLinkResponseCursorPagination: This is similar to LinkHeaderCursorPagination, but in addition to the next and/or prev URL's being in the Link header, the content of the response body is updated to include them as well. The body will be an object with the keys next (the next page's URL or None), previous (the previous page's URL or None), and results (the original content of the body).
• LinkHeaderLimitOffsetPagination: Uses the LimitOffsetPagination pagination class from DRF to support offset and limit parameters instead of page to indicate offset into the queryset.

Configuration

The configuration is the same as for PageNumberPagination.

Testing

Use the excellent tox testing tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:

$ tox