Skip to main content

Extension for Django Rest Framework to enable simple sideloading

Project description

Package Index Build Status Code Coverage License is MIT Code style Black

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

:warning: Python 2 and Django 1.11 are no longer supported from version 1.4.0!

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.


  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/
sh scripts/


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


$ make test

Run tests with environment matrix

$ make tox

Run tests with specific environment

$ tox --listenvs
# ...
$ tox -e py39-django32-drf312

Test coverage

$ make coverage

Use pyenv for testing using different python versions locally.





1.4.2 (2021-04-12)

  • Add support for lists in filter_related_objects

1.4.1 (2021-04-09)

  • Fix sideloadable prefetches

1.4.0 (2021-04-07)

  • Python supported versions 3.6 -> 3.9
  • Django supported versions 2.2, 3.1, 3.2
  • Django-rest-framework supported versions. 3.9 -> 3.12

1.3.1 (2021-04-07)

Added support for django.db.models.Prefetch

1.3.0 (2019-04-23)

Fix empty related fields sideloading bug

  • Support for Django 2.2

1.2.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.

Project details

Download files

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

Files for drf-sideloading, version 1.4.2
Filename, size File type Python version Upload date Hashes
Filename, size drf_sideloading-1.4.2-py2.py3-none-any.whl (8.3 kB) File type Wheel Python version py2.py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page