drf-parcel¶
One response shape for a Django REST framework API - success, page and error alike - and the generated schema saying exactly that shape.
{"success": false, "status_code": 409, "message": "There is not enough of this product in stock.",
"data": {"available": 0}, "error_code": "out_of_stock"}
A client reads one shape and never special-cases a payload: the answer is
under data, a person reads message, and code branches on error_code -
never on the message, which is translated.
- Every answer in one envelope - a viewset, a plain
APIView, a custom@action, a page and a failure alike, with a message that says what happened. - Pages by number or by cursor, chosen per view; the client chooses the page size where you allow it, and never gets more than the ceiling.
- Every failure in the same envelope - each field's problem with its
code, DRF's and Django's errors with a standard code, your own errors with
the
dataa client acts on, and a bug that never tells its secrets. - The schema says what arrives - drf-spectacular documents the envelope,
not only what is inside it, so a generated client reads
response.data.id.
Your existing APIExceptions keep working, unchanged. Each part is used
alone, so a project adopts it one view at a time. Every sentence comes in
English and Persian.
Install¶
INSTALLED_APPS = [..., 'rest_framework', 'drf_parcel']
REST_FRAMEWORK = {
'EXCEPTION_HANDLER': 'drf_parcel.handlers.exception_handler',
'DEFAULT_PAGINATION_CLASS': 'drf_parcel.pagination.PageNumberPagination',
'DEFAULT_SCHEMA_CLASS': 'drf_parcel.schema.ParcelAutoSchema',
}
Where to go next¶
| Quickstart | a first view in the envelope, in five minutes |
| The tutorial | the example shop, built a part at a time |
| How-to guides | one question a project meets, answered in a few steps - adopting it in an existing project first |
| The contract | every shape, every error code, every setting - what the code promises |
| Reference | settings, error codes, start-up checks, and the Python API |
| Explanation | why it is built the way it is, and how it compares |
| Questions | what people ask first |
| The example shop | a project using all of it, to run |
Python 3.11 to 3.14; Django 5.2, 6.0 and 6.1; Django REST framework 3.16 and later; drf-spectacular 0.28 and later, for the schema.