djangorestframework-expander

A serializer mixin for Django REST Framework to expand object representations inline

Requirements

Python (2.7, 3.2, 3.3, 3.4, 3.5)
Django (1.7, 1.8, 1.9)
Django REST Framework (3.1, 3.2, 3.3)

Installation

Install using pip

pip install djangorestframework-expander

Quick Start

Must inherit from ExpanderSerializerMixin
Expandable fields are defined using the expandable_fields attribute on the serializer Meta class.
- Key is the field name.
- Value is the serializer class - e.g. MenuItemSerializer OR
- Value is a 3 tuple of (class, args, kwargs) - e.g. (MenuItemSerializer, (), {'many': True})
NOTE field does not have to appear in fields to appear in expandable_fields.
Expansion is controlled using the expand URL paramter. e.g. /menu-items/?expand=menu
Expand multiple fields with a comma. e.g. /menu-items/?expand=menu,price_bracket
Expand nested fields by using a dot. e.g. /menu-items/?expand=menu.restaurant

Configuration

The available configuration options using settings.py and their defaults.

DRF_EXPANDER_EXPAND_ARG = 'expand' - The request query param that will be used to indicate which fields to expand.

Example

from expander import ExpanderSerializerMixin

class RestaurantSerializer(ExpanderSerializerMixin, serializers.ModelSerializer):
    class Meta:
        model = Restaurant
        fields = ('id', 'title')

class MenuSerializer(ExpanderSerializerMixin, serializers.ModelSerializer):
    class Meta:
        model = Menu
        fields = ('id', 'restaurant', 'title')
        expandable_fields = {
            'restaurant': RestaurantSerializer,
        }

class PriceBracketSerializer(serializers.ModelSerializer):
    class Meta:
        model = PriceBracket
        fields = ('id', 'title')

class MenuItemSerializer(ExpanderSerializerMixin, serializers.ModelSerializer):
    class Meta:
        model = MenuItem
        fields = ('id', 'menu', 'title', 'description', 'price', 'price_bracket')
        expandable_fields = {
            'menu': MenuSerializer,
            'price_bracket': PriceBracketSerializer,
        }

Making a request for a menu item returns the usual results to start with.

GET /menu-items/1/

{
    "id": 1,
    "menu": 3,
    "title": "Breakfast",
    "description": "",
    "price": "3.50"
}

Expand menu

GET /menu-items/1/?expand=menu

{
    "id": 1,
    "menu": {
        "id": 3,
        "restaurant": 6,
        "title": "Breakfast"
    },
    "title": "Eggs",
    "description": "",
    "price": "3.50"
}

Expand nested

GET /menu-items/1/?expand=menu.restaurant

{
    "id": 1,
    "menu": {
        "id": 3,
        "restaurant": {
            "id": 6,
            "title": "Bob's Bed and Breakfast"
        },
        "title": "Breakfast"
    },
    "title": "Eggs",
    "description": "",
    "price": "3.50"
}