Skip to content
A serializer mixin for Django REST Framework to expand object representations inline
Branch: master
Clone or download
Latest commit b1cf60c Oct 13, 2016
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
expander fix bug when expand arg is missing intermediate expansion Oct 13, 2016
tests
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
README.md
setup.cfg
setup.py
tox.ini

README.md

djangorestframework-expander

Build Status

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"
}
You can’t perform that action at this time.