README.md

Django REST framework serializer extensions

A collection of useful tools to DRY up your Django Rest Framework serializers

Full documentation: http://django-rest-framework-serializer-extensions.readthedocs.io/

Overview

Serializer extensions reduces the need for very similar serializers, by allowing the fields to be defined on a per-view/request basis. Fields can be whitelisted, blacklisted, and child serializers can be optionally expanded. Whatever fields you choose to use, your querysets can be optimized automatically to make the fewest database calls possible.

Support for HashIds is also provided. If you're currently exposing your internal IDs over a public API, we suggest you consider switching to HashIds instead.

⭐ Lovingly open-sourced by Housekeep.

Requirements

Tested against:

• Python (3.8, 3.9, 3.10, 3.11, 3.12)
• Django (3.2, 4.2, 5.0)
• Django REST Framework (3.12, 3.13, 3.14, 3.15). Note Django REST Framework 3.15 is the first version to officially support Django 4.2+.
• HashIds (>1.0)

Installation

Install using pip:

$ pip install djangorestframework-serializer-extensions

And add rest_framework_serializer_extensions to your INSTALLED_APPS setting:

INSTALLED_APPS = (
    ...
    'rest_framework_serializer_extensions'
)

Basic Usage

To activate the serializer extensions, add the SerializerExtensionsMixin to your serializers:

# serializers.py
from rest_framework.serializers import ModelSerializer
from rest_framework_serializer_extensions.serializers import SerializerExtensionsMixin

...

class OwnerSerializer(SerializerExtensionsMixin, ModelSerializer):
    class Meta:
        model = models.Owner
        fields = ('id', 'name')
        expandable_fields = dict(
            organization=OrganizationSerializer,
            cars=dict(
                serializer=SkuSerializer,
                many=True
            )
        )

And add the SerializerExtensionsAPIViewMixin to your API views:

from rest_framework.generics import RetrieveAPIView
from rest_framework_serializer_extensions.views import SerializerExtensionsAPIViewMixin

class RetriveOwnerAPIView(SerializerExtensionsAPIViewMixin, RetrieveAPIView):
    ...

Examples

Serializer extensions allows your API to re-use your serializers to fit a variety of use cases. The examples shown below use query parameters to modify the response, but individual views can interact with your serializers in much the same way.

>>> GET /owner/x4F/
{
  "id": 'x4F',
  "name": 'tyrell',
  "organization_id": 'kgD'
}

>>> GET /owner/x4F/?expand=organization
{
  "id": 'x4F',
  "name": 'tyrell',
  "organization_id": 'kgD',
  "organization": {
    "id": "kgD",
    "name": "E Corp"
  }
}

>>> GET /owner/x4F/?expand=cars__model&exclude=name
{
  "id": 'x4F',
  "organization_id": 'kgD',
  "cars": [
    {
      "id": "wf9",
      "variant": "P100D",
      "model": {
        "id": "ncX",
        "name": "Model S"
      }
    }
  ]
}

>>> GET /owner/x4F/?expand=cars&only=cars__variant
{
  "cars": [
    {
      "variant": "P100D",
    }
  ]
}

Testing

Install testing requirements.

$ pip install -e .[test]

Run with pytest

$ pytest

You can also use the excellent tox testing tool to run the tests against all supported versions of Python and Django. Install tox globally, and then simply run:

$ tox

Documentation

To build the documentation, you’ll need to install mkdocs. These are included in the development extras:

$ pip install -e .[dev]

To preview the documentation:

$ mkdocs serve
Running at: http://127.0.0.1:8000/

To build the documentation:

$ mkdocs build