drf-sideloading 1.2.0

Extension for Django Rest Framework to enable simple sideloading

:warning: Note that there are major API changes since version 0.1.1 that have to be taken into account when upgrading!

Django rest framework sideloading

DRF-sideloading is an extension to provide side-loading functionality of related resources. Side-loading allows related resources to be optionally included in a single API response minimizing requests to the API.

Quickstart

1. Install drf-sideloading:

pip install drf-sideloading

2. Import SideloadableRelationsMixin:

from drf_sideloading.mixins import SideloadableRelationsMixin

3. Write your SideLoadableSerializer You need to define the primary serializer in the Meta data and can define prefetching rules. Also notice the many=True on the sideloadable relationships.

from drf_sideloading.serializers import SideLoadableSerializer

class ProductSideloadableSerializer(SideLoadableSerializer):
    products = ProductSerializer(many=True)
    categories = CategorySerializer(source="category", many=True)
    suppliers = SupplierSerializer(source="supplier", many=True)
    partners = PartnerSerializer(many=True)

    class Meta:
        primary = "products"
        prefetches = {
            "categories": "category",
            "suppliers": "supplier",
            "partners": "partners",
        }

4. Configure sideloading Include SideloadableRelationsMixin mixin in ViewSet and define sideloading_serializer_class as shown in example below. Evrything else stays just like a regular ViewSet

from drf_sideloading.mixins import SideloadableRelationsMixin

class ProductViewSet(SideloadableRelationsMixin, viewsets.ModelViewSet):
    """
    A simple ViewSet for viewing and editing products.
    """

    queryset = Product.objects.all()
    serializer_class = ProductSerializer
    sideloading_serializer_class = ProductSideloadableSerializer

5. Enjoy your API with sideloading support

GET /api/products/?sideload=categories,partners,suppliers,products

{
  "products": [
    {
      "id": 1,
      "name": "Product 1",
      "category": 1,
      "supplier": 1,
      "partners": [1, 2, 3]
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "Category1"
    }
  ],
  "suppliers": [
    {
      "id": 1,
      "name": "Supplier1"
    }
  ],
  "partners": [
    {
      "id": 1,
      "name": "Partner1"
    },
    {
      "id": 2,
      "name": "Partner1"
    },
    {
      "id": 3,
      "name": "Partner3"
    }
  ]
}

Example Project

Directory example contains an example project using django rest framework sideloading library. You can set it up and run it locally using following commands:

cd example
sh scripts/devsetup.sh
sh scripts/dev.sh

Contributing

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

Setup for contribution

source <YOURVIRTUALENV>/bin/activate
(myenv) $ pip install -r requirements_dev.txt

Test

$ make test

Run tests with environment matrix

$ make tox

Run tests with specific environment

$ tox --listenvs
py27-django18-drf34
py27-django19-drf34
# ...
$ tox -e py27-django19-drf34

Test coverage

$ make coverage

Use pyenv for testing using different python versions locally.

License

MIT

Credits

• Demur Nodia
• Tõnis Väin
• Madis Väin
• Lenno Nagel

Changelog

1.0.0 (2018-10-29)

Completely refactored sideloading configuration via a custom serializer.

• Support for Django 2.1
• Support for Django-rest-framework 3.9

0.1.10 (2017-07-20)

• Support for Django 2.0

0.1.8 (2017-07-20)

• change sideloadable_relations dict
• always required to define 'serializer'
• key is referenced to url and serialized in as rendered json
• add source which specifies original model field name

0.1.0 (2017-07-20)

• First release on PyPI.