Extension for Django Rest Framework to enable simple sideloading
Project description
: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
-
Install drf-sideloading:
pip install drf-sideloading
-
Import
SideloadableRelationsMixin
:from drf_sideloading.mixins import SideloadableRelationsMixin
-
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", }
-
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
-
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
Credits
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for drf_sideloading-1.4.2-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d3d4927ac7f2fecb99a669b6dcc6e28d4190cfbd4d070096c21c67f98aa7dbfa |
|
MD5 | 55dae0672e703e88e984d16bd8f0d8b3 |
|
BLAKE2b-256 | d68cbe5d7a2bd4bf4a933cdd4fa5c688cdc815d19ab7ab2ac8ae169bdd80b8fe |