Skip to content

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": true,  "status_code": 200, "message": "Done.", "data": {"id": 7, "name": "Ring"}}
{"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 data a 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

pip install 'drf-parcel[schema]'
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.