Skip to main content

Extensions to DRY up Django Rest Framework serializers

Project description

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

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

build-status-image coverage-status-image pypi-version

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.

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.

:star: Lovingly open-sourced by `Housekeep <https://housekeep.com>`__.

Requirements

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 -r requirements.txt

Run with runtests.

$ ./runtests.py

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.

$ pip install mkdocs

To preview the documentation:

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

To build the documentation:

$ mkdocs build

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page