# Enhanced Django REST framework JSON:API

Shared, tested primitives used by several django projects on top of
[`djangorestframework-jsonapi`](https://github.com/django-json-api/django-rest-framework-json-api).

## 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

```python
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:

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

Alternatively, opt individual classes in:

```python
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:

```python
from enhanced_drf_jsonapi.exceptions import APIConflictException

raise APIConflictException()
```

## Development

```bash
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.