Integrations

Serializing QuerySets into models

Django is built around its QuerySet type. Of course, we have to make sure that it is supported.

Let’s say you have these models that you already work with:

models.py

Show imports... 3 lines hidden

[source]

from django.db import models


class Tag(models.Model):
    name = models.CharField(max_length=100)

    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)


class Role(models.Model):
    name = models.CharField(max_length=100)

    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)


class User(models.Model):
    email = models.EmailField(unique=True)

    role = models.ForeignKey(
        Role,
        on_delete=models.CASCADE,
        related_name='users',
    )
    tags = models.ManyToManyField(Tag, related_name='users')

    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

Now, let’s create an API that will work with your models. To do that the first thing you need to do is to create your API serializers / deserializers.

While it may seems that this is a redundant duplication of code, and that it should be possible to build serialization schemas out of Django models, but that’s actually the opposite.

Because models and serialization schemes must change independenly. Otherwise, your API would be a mess and will change unexpectedly, when you create a new migration. This problem happened to me too many times.

serializers.py

Show imports... 6 lines hidden

[source]

import datetime as dt
from typing import final

import pydantic


@final
class TagSchema(pydantic.BaseModel):
    name: str


@final
class RoleSchema(pydantic.BaseModel):
    name: str


class UserCreateSchema(pydantic.BaseModel):
    email: str
    role: RoleSchema
    tags: list[TagSchema]


@final
class UserSchema(UserCreateSchema):
    id: int
    created_at: dt.datetime

Important

Models and QuerySets can’t be serialized to json by default. This is a design choice, this is a feature.

Why?

Because Models and QuerySets are not designed for serialization, they are designed for the database access. Mixing these two layers will complicate, not simplify, your app.

Now, let’s create a service to build your model instances:

services.py

Show imports... 6 lines hidden

[source]

from django.db import IntegrityError, transaction

from server.apps.models_example import serializers
from server.apps.models_example.models import Role, Tag, User


class UniqueEmailError(Exception):
    """Email must be unique."""


def user_create_service(user_schema: serializers.UserCreateSchema) -> User:
    """This is a function just for the demo purpose, it is usually a class."""
    with transaction.atomic():
        role = Role.objects.create(name=user_schema.role.name)

        try:
            user = User.objects.create(
                email=user_schema.email,
                role_id=role.pk,
            )
        except IntegrityError:
            raise UniqueEmailError from None

        # Handle m2m:
        tags = Tag.objects.bulk_create([
            Tag(name=tag.name) for tag in user_schema.tags
        ])
        user.tags.set(tags)
    return user

Here’s how the final Controller would look like:

views.py

Show imports... 21 lines hidden

[source]

from http import HTTPStatus
from typing import final

from django.http import HttpResponse
from typing_extensions import override

from dmr import Body, Controller, modify
from dmr.endpoint import Endpoint
from dmr.errors import ErrorModel, ErrorType
from dmr.metadata import ResponseSpec
from dmr.plugins.pydantic import PydanticSerializer
from server.apps.models_example.serializers import (
    UserCreateSchema,
    UserSchema,
)
from server.apps.models_example.services import (
    UniqueEmailError,
    user_create_service,
)


@final
class UserCreateController(Controller[PydanticSerializer]):
    @modify(
        extra_responses=[
            ResponseSpec(
                ErrorModel,
                status_code=HTTPStatus.CONFLICT,
            ),
        ],
    )
    def post(self, parsed_body: Body[UserCreateSchema]) -> UserSchema:
        user = user_create_service(parsed_body)
        return UserSchema(
            id=user.pk,
            created_at=user.created_at,
            email=user.email,
            role=parsed_body.role,
            tags=parsed_body.tags,
        )

    @override
    def handle_error(
        self,
        endpoint: Endpoint,
        controller: Controller[PydanticSerializer],
        exc: Exception,
    ) -> HttpResponse:
        # Handle custom errors that can happen in this controller:
        if isinstance(exc, UniqueEmailError):
            return self.to_error(
                self.format_error(
                    'User email must be unique',
                    error_type=ErrorType.value_error,
                ),
                status_code=HTTPStatus.CONFLICT,
            )
        # Handle default errors:
        return super().handle_error(endpoint, controller, exc)

Now you have your REST API that returns fully typed model responses and can work with QuerySet and Model instances.

django-mantle

If you want to automate this part and automatically convert QuerySet into typed models, you can use django-mantle which is built just for this purpose:

views.py

Show imports... 6 lines hidden

[source]

import attrs

from dmr import Controller
from dmr.plugins.msgspec import MsgspecSerializer


@attrs.define
class _UserModel:
    username: str
    email: str
    is_active: bool


class UsersController(Controller[MsgspecSerializer]):
    def get(self) -> list[_UserModel]:
        # We have to do import here due to how our docs build systems works,
        # but in real apps they must be on the module level:
        from django.contrib.auth.models import User  # noqa: PLC0415
        from mantle import Query  # noqa: PLC0415

        return Query(User.objects.all(), _UserModel).all()

Run result

$ curl http://127.0.0.1:8000/api/users/ -X GET
[{"email":"test@example.com","is_active":true,"username":"test_user"}]

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array"
          },
          "msg": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_UserModel": {
        "properties": {
          "email": {
            "type": "string"
          },
          "is_active": {
            "type": "boolean"
          },
          "username": {
            "type": "string"
          }
        },
        "required": [
          "username",
          "email",
          "is_active"
        ],
        "title": "_UserModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/userscontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getUserscontrollerApiUserscontroller",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/_UserModel"
                  },
                  "type": "array"
                }
              }
            },
            "description": "OK"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

CSRF

Django supports Cross Site Request Forgery protection.

By default we exempt all controllers from CSRF checks, unless:

1. csrf_exempt is set to False for a specific controller

2. Endpoints protected by DjangoSessionSyncAuth or DjangoSessionAsyncAuth will require CSRF as well. Because using Django sessions without CSRF is not secure

Bring your own DI

We don’t have any opinions about any DI that you can potentially use. Because django-modern-rest is compatible with any of the existing ones.

Use any DI that you already have or want to use with django.

Try any of these officially recommended tools:

• https://github.com/maksimzayats/diwire with the official django-modern-rest how-to

• https://github.com/reagento/dishka with the help of https://github.com/arturboyun/dmr-dishka plugin

• https://github.com/bobthemighty/punq

Or any other one that suits your needs :)

Typing

Django does not have type annotations, by default, so mypy won’t type check Django apps by default. But, when django-stubs is installed, type checking starts to shine.

So, when you use mypy, you will need to install django-stubs together with django-modern-rest to have the best type checking experience.

This package is included in pyright by default. No actions are required.

We check django-modern-rest code with mypy and pyright strict modes in CI, so be sure to have the best typing possible.

See our project template to learn how typing works, how mypy is configured, how django-stubs is used.

Pagination

We don’t ship our own pagination. We (as our main design goal suggests) provide support for any existing pagination plugin for Django. Including the built-in django.core.paginator.Paginator.

To do so, we only provide metadata for the default pagination:

views.py

Show imports... 10 lines hidden

[source]

from typing import Final, NotRequired, TypedDict

import pydantic
from django.core.paginator import Paginator

from dmr import Controller, Query
from dmr.pagination import Page, Paginated
from dmr.plugins.pydantic import PydanticSerializer


class _User(pydantic.BaseModel):
    email: str


class _PageQuery(TypedDict):
    page_size: NotRequired[int]
    page: NotRequired[int]


_USERS: Final = (
    _User(email='one@example.com'),
    _User(email='two@example.com'),
    _User(email='three@example.com'),
)


class UsersController(
    Controller[PydanticSerializer],
):
    def get(self, parsed_query: Query[_PageQuery]) -> Paginated[_User]:
        page = parsed_query.get('page', 1)
        page_size = parsed_query.get('page_size', 2)

        paginator = Paginator(_USERS, page_size)
        return Paginated(
            count=paginator.count,
            num_pages=paginator.num_pages,
            per_page=paginator.per_page,
            page=Page(
                number=page,
                object_list=list(paginator.page(page).object_list),
            ),
        )

Run result

$ curl http://127.0.0.1:8000/api/users/ -X GET
{"count":3,"num_pages":2,"per_page":2,"page":{"number":1,"object_list":[{"email":"one@example.com"},{"email":"two@example.com"}]}}

$ curl 'http://127.0.0.1:8000/api/users/?page=2' -X GET
{"count":3,"num_pages":2,"per_page":2,"page":{"number":2,"object_list":[{"email":"three@example.com"}]}}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "Page__User_": {
        "properties": {
          "number": {
            "title": "Number",
            "type": "integer"
          },
          "object_list": {
            "items": {
              "$ref": "#/components/schemas/_User"
            },
            "title": "Object List",
            "type": "array"
          }
        },
        "required": [
          "number",
          "object_list"
        ],
        "title": "Page",
        "type": "object"
      },
      "Paginated": {
        "properties": {
          "count": {
            "title": "Count",
            "type": "integer"
          },
          "num_pages": {
            "title": "Num Pages",
            "type": "integer"
          },
          "page": {
            "$ref": "#/components/schemas/Page__User_"
          },
          "per_page": {
            "title": "Per Page",
            "type": "integer"
          }
        },
        "required": [
          "count",
          "num_pages",
          "per_page",
          "page"
        ],
        "title": "Paginated",
        "type": "object"
      },
      "_User": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "_User",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/userscontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getUserscontrollerApiUserscontroller",
        "parameters": [
          {
            "deprecated": false,
            "in": "query",
            "name": "page_size",
            "schema": {
              "title": "Page Size",
              "type": "integer"
            }
          },
          {
            "deprecated": false,
            "in": "query",
            "name": "page",
            "schema": {
              "title": "Page",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Paginated"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        }
      }
    }
  }
}

If you are using a different pagination system, you can define your own metadata / models and use them with our framework.

class dmr.pagination.Paginated(*, count: int, num_pages: int, per_page: int, page: Page[_ModelT])

Helper type to serialize the default Paginator object.

Django already ships a pagination system, we don’t want to replicate it. So, we only provide metadata. See django.core.paginator.Paginator for the exact API.

class dmr.pagination.Page(*, number: int, object_list: Sequence[_ModelT])

Default page model for serialization.

Can be used when using pagination with django-modern-rest.

django-filters

No special integration with django-filter is required.

Everything just works.

import django_filters
import pydantic
from dmr import Controller, Query
from dmr.plugins.pydantic import PydanticSerializer

from your_app.models import User

class UserFilter(django_filters.FilterSet):
    class Meta:
        model = User
        fields = ('is_active',)

# Create query model for better docs:
class QueryModel(pydantic.BaseModel):
    is_active: bool

class UserModel(pydantic.BaseModel):
    username: str
    email: str
    is_active: bool

class UserListController(
    Controller[PydanticSerializer],
    Query[QueryModel],
):
    def get(self) -> list[UserModel]:
        # Still pass `.GET` for API compatibility:
        user_filter = UserFilter(
             self.request.GET,
             queryset=User.objects.all(),
        )
        return [
            UserModel.model_validate(user, from_attributes=True)
            for user in user_filter.qs
        ]

CORS Headers

No special integration with django-cors-headers is required.

Everything just works.

Conditional requests (ETag)

Django has built-in support for conditional request processing (If-None-Match, If-Modified-Since, 304 Not Modified):

With django-modern-rest you can integrate it via wrap_middleware() and django.views.decorators.http.condition().

etag.py

Show imports... 16 lines hidden

[source]

from datetime import UTC, datetime
from http import HTTPStatus
from types import MappingProxyType
from typing import Any, Final, final

import pydantic
from django.http import HttpRequest, HttpResponse
from django.views.decorators.http import condition

from dmr import Controller, HeaderSpec, Path, ResponseSpec
from dmr.decorators import wrap_middleware
from dmr.errors import ErrorType
from dmr.plugins.pydantic import PydanticSerializer
from dmr.response import APIError


@final
class _UserModel(pydantic.BaseModel):
    user_id: int
    updated_at: datetime
    message: str


@final
class _PathModel(pydantic.BaseModel):
    user_id: int


@final
class _ResponseModel(pydantic.BaseModel):
    message: str
    updated_at: str


# Imitate DB
_USERS: Final = MappingProxyType({
    1: _UserModel(
        user_id=1,
        updated_at=datetime(2026, 3, 23, 12, 30, tzinfo=UTC),  # noqa: WPS432
        message='Fresh content for user #1',
    ),
    2: _UserModel(
        user_id=2,
        updated_at=datetime(2026, 3, 24, 9, 15, tzinfo=UTC),  # noqa: WPS432
        message='Fresh content for user #2',
    ),
})


def _build_etag(user: _UserModel) -> str:
    updated_at = user.updated_at.isoformat()
    return f'"user-{user.user_id}-{updated_at}"'


def _etag(request: HttpRequest, user_id: int = 0, **kwargs: Any) -> str | None:
    user = _USERS.get(user_id)
    return _build_etag(user) if user else None


@wrap_middleware(
    condition(etag_func=_etag),
    ResponseSpec(return_type=_ResponseModel, status_code=HTTPStatus.OK),
    ResponseSpec(
        return_type=None,
        status_code=HTTPStatus.NOT_MODIFIED,
        headers={'ETag': HeaderSpec()},
    ),
)
def _condition_middleware(response: HttpResponse) -> HttpResponse:
    """Adds Content-Type for 304 responses to satisfy strict validation."""
    if response.status_code == HTTPStatus.NOT_MODIFIED:
        response.headers['Content-Type'] = 'application/json'
    return response


@final
@_condition_middleware
class ConditionalETagController(Controller[PydanticSerializer]):
    responses = _condition_middleware.responses

    def get(self, parsed_path: Path[_PathModel]) -> HttpResponse:
        user = _USERS.get(parsed_path.user_id)
        if user is None:
            raise APIError(
                self.format_error(
                    f'User {parsed_path.user_id} not found',
                    error_type=ErrorType.not_found,
                ),
                status_code=HTTPStatus.NOT_FOUND,
            )
        return self.to_response(
            _ResponseModel(
                message=user.message,
                updated_at=user.updated_at.isoformat(),
            ),
        )

Run result

$ curl http://127.0.0.1:8000/api/example/1/ -D - -X GET
HTTP/1.1 200 OK
date: Sun, 29 Mar 2026 18:52:52 GMT
server: uvicorn
Content-Type: application/json
ETag: "user-1-2026-03-23T12:30:00+00:00"
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 80
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"message":"Fresh content for user #1","updated_at":"2026-03-23T12:30:00+00:00"}

$ curl http://127.0.0.1:8000/api/example/1/ -D - -X GET -H 'If-None-Match: "user-1-2026-03-23T12:30:00+00:00"'
HTTP/1.1 304 Not Modified
date: Sun, 29 Mar 2026 18:52:52 GMT
server: uvicorn
ETag: "user-1-2026-03-23T12:30:00+00:00"
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 0
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin


$ curl http://127.0.0.1:8000/api/example/2/ -D - -X GET
HTTP/1.1 200 OK
date: Sun, 29 Mar 2026 18:52:52 GMT
server: uvicorn
Content-Type: application/json
ETag: "user-2-2026-03-24T09:15:00+00:00"
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 80
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"message":"Fresh content for user #2","updated_at":"2026-03-24T09:15:00+00:00"}

See also

https://docs.djangoproject.com/en/stable/topics/conditional-view-processing