Django rest framework sideloading
Switch branches/tags
Nothing to show
Clone or download
madisvain Merge pull request #43 from namespace-ee/test-fixes
Bump version: 1.1.1 → 1.2.0
Latest commit 2f47bf4 Nov 28, 2018

README.md

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

⚠️ 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
  1. Import SideloadableRelationsMixin:
from drf_sideloading.mixins import SideloadableRelationsMixin
  1. 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",
        }
  1. 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
  1. 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