85 lines
2.6 KiB
Markdown
85 lines
2.6 KiB
Markdown
# 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.
|