enhanced-drf-jsonapi/README.md

Enhanced Django REST framework JSON:API

Shared, tested primitives used by several django projects on top of djangorestframework-jsonapi.

Compatibility

• Python 3.10–3.14
• djangorestframework-jsonapi 7.1 and 8.1
• The Django and Django REST framework releases accepted by the selected djangorestframework-jsonapi version

The GitLab test matrix exercises every supported Python/DRF JSON:API combination. Applications may stay on 7.1 while upgrading independently, then move to 8.1 without changing imports from this package.

API primitives

from enhanced_drf_jsonapi.api import (
    ReasonableModelSerializer,
    ReasonableModelViewSet,
    basic_filter,
    date_filter,
    int_filter,
    text_filter,
)
from enhanced_drf_jsonapi.pagination import NgxJsonApiPageNumberPagination

• PreloadIncludesMixin applies select_for_includes and prefetch_for_includes rules for requested JSON:API relationships.
• ReasonableModelViewSet exposes the standard resource methods and combines the JSON:API relationship/prefetch mixins.
• ReasonableModelSerializer includes declared relationship fields requested through GET includes and POST/PATCH payloads.
• NgxJsonApiPageNumberPagination preserves the pagination metadata and link shape expected by ngx-jsonapi clients.

Hardened exception handling

Use the handler globally so every DRF view, including plain APIView classes, returns the same JSON:API error shape:

REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": (
        "enhanced_drf_jsonapi.exceptions.hardened_exception_handler"
    ),
}

Alternatively, opt individual classes in:

from enhanced_drf_jsonapi.api import HardenedGenericAPIView, HardenedModelViewSet

Expected DRF exceptions retain their status and detail. Unexpected exceptions are logged with a generated error identifier and returned as a sanitized HTTP 500 response carrying the same identifier in X-Error-ID. Internal exception messages and tracebacks are never included in the response.

Known application conflicts must be raised deliberately rather than treating every database integrity failure as a client error:

from enhanced_drf_jsonapi.exceptions import APIConflictException

raise APIConflictException()

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m build
python -m twine check dist/*

Run all locally available compatibility environments with tox. CI runs the complete Python 3.10–3.14 × DRF JSON:API 7.1/8.1 matrix.