django-reversion-rest-framework

A package for adding a django-reversion history endpoint to django-rest-framework ModelViewSet.

Requirements

• Python 3.10+
• Django 5.2, 6.0, or 6.1
• django-reversion 4+
• djangorestframework 3+

Django 6.1 requires djangorestframework>=3.18.

Installation

pip install django-reversion-rest-framework

Configuration

Follow the official website for the installation and the integration of django-reversion in your project, otherwise future steps won't work.

You might need to enable the ReversionMiddleware for storing a version for each API change.
Follow the instructions here, you should add 'reversion.middleware.RevisionMiddleware' to your MIDDLEWARE setting.

Using the HistoryModelViewSet

The HistoryModelViewSet extends django-rest-framework's ModelViewSet adding

• a GET history action in the detail (/my-model-url/<pk>/history/)

  displaying a list of all revisions of that specific record

• a GET version action in the history detail (/my-model-url/<pk>/history/<version_pk>/)

  displaying a specific revisions of that specific record

• a GET deleted action in the list (/my-model-url/deleted/)

  displaying a list of deleted records (see Scoping deleted records)

• a POST revert action in the detail (/my-model-url/<pk>/revert/<version_pk>/)

  allowing users to revert to a previous revision of the object

• a POST restore action in the list (/my-model-url/restore/<version_pk>/)

  allowing users to restore a deleted object from its version history

You can use the HistoryModelViewSet in place of the ModelViewSet during viewsets definition.

from reversion_rest_framework.viewsets import HistoryModelViewSet


class MyModelViewSet(HistoryModelViewSet):
    # ...

For advanced or selective implementation, you can use reversion_rest_framework.mixins.

• HistoryMixin contains history and version actions

• DeletedMixin contains only the deleted action

• RestoreMixin contains deleted and restore actions

• RevertMixin contains history, version and revert actions

from rest_framework.viewsets import ModelViewSet
from reversion_rest_framework.mixins import HistoryMixin, DeletedMixin


class ReadOnlyHistoryViewSet(HistoryMixin, DeletedMixin, ModelViewSet):
    # history + version + deleted, without revert
    # ...

Scoping deleted records

Deleted objects are no longer in the database, so get_queryset() can't scope the deleted and restore actions. Both use get_deleted_versions(). django-reversion doesn't record deletions, so a deleted record's version is the one from its last save: by default get_deleted_versions() returns only the deleted records last saved by the requesting user (none for anonymous users). Records last saved without a user (e.g. from a management command) are not returned.

restore also checks the restored record against get_queryset(): if the record isn't in it, the restore is rolled back and a 404 is returned.

Override it to match your access rules, for example to let every user see every deleted record:

from reversion.models import Version
from reversion_rest_framework.viewsets import HistoryModelViewSet


class MyModelViewSet(HistoryModelViewSet):
    def get_deleted_versions(self):
        return Version.objects.get_deleted(MyModel)

Filtering history and deleted

The history and deleted endpoints support filtering by revision fields via query parameters:

For example: /my-model-url/<pk>/history/?date_created__gt=2024-01-01T00:00:00Z&user=12

Customizing the VersionSerializer

The HistoryModelViewSet comes up with actions using a VersionSerializer.
To customize the serializer with one of your own, you can use version_serializer.
For example, if you want to customize the user serializer inside a revision, you can use the following code:

from django.contrib.auth.models import User
from rest_framework import serializers
from reversion.models import Revision, Version
from reversion_rest_framework.serializers import (
    RevisionSerializer,
    VersionSerializer,
)
from reversion_rest_framework.viewsets import HistoryModelViewSet


class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username"]


class CustomRevisionSerializer(RevisionSerializer):
    user = UserSerializer()


class CustomVersionSerializer(VersionSerializer):
    revision = CustomRevisionSerializer()


class MyModelViewSet(HistoryModelViewSet):
    version_serializer = CustomVersionSerializer
    # ...