drf-sideloading 1.4.2

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!

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

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
py37-django22-drf39
py38-django31-drf311
py39-django32-drf312
# ...
$ tox -e py39-django32-drf312

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