Core concepts¶

To learn django-modern-rest you have to learn just a couple of things:

Endpoint¶: Endpoint is a single API route. It is defined by its name – HTTP method – and its Metadata, what response schema it returns, what status codes it can return, etc. Each endpoint might have different Component types for parsing the inputs.
Controller¶: Controller is a collection of one or more endpoints with the same set of components. Controller is a subclass of View, so it can be used in a routing directly.
Component¶: Controllers parse data via components like Body or Headers. You can write your own components.
Metadata¶: A collection of all the things each Endpoint accepts and returns. It is used for request parsing, response validation, and OpenAPI schema.
Serializer¶: BaseSerializer subclass that knows how to load and dump raw data into models. We have 2 bundled serializers in plugins: for pydantic and msgspec, you can write your own serializers for other libraries.
Routing¶: Routing is a mapping of URLs to controllers. We use default Django’s URL routing. Controllers might have many URLs, for example: /api/v1/users/ and /api/v2/users/

Example:

views.py¶

import uuid

import msgspec

from dmr import Body, Controller, NewHeader, modify
from dmr.plugins.msgspec import MsgspecSerializer


class UserCreateModel(msgspec.Struct):
    email: str


class UserModel(UserCreateModel):
    uid: uuid.UUID


class UserController(  # <- `Controller` definition
    Controller[MsgspecSerializer],  # <- Passing `Serializer`
):
    @modify(headers={'X-Default': NewHeader(value='1')})  # <- extra `Metadata`
    def post(
        self,
        parsed_body: Body[UserCreateModel],
    ) -> UserModel:  # <- `Endpoint` definition
        return UserModel(uid=uuid.uuid4(), email=parsed_body.email)

Run result

$ curl http://127.0.0.1:8000/api/user/ -D - -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json'
HTTP/1.1 201 Created
date: Sun, 29 Mar 2026 18:52:44 GMT
server: uvicorn
Content-Type: application/json
X-Default: 1
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 69
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"email":"user@wms.org","uid":"2f5a9fd4-3ab1-4e76-b266-bcc152d279cb"}

Async vs Sync¶

We support both Django modes: sync and async, the same way regular Django supports them.

We don’t do anything special with the async mode, so any existing guides, tools, deployment strategies should just work with django-modern-rest if they work for Django.

Maximum integration with Django¶

We try to keep Django compatibility as our main goal. Everything should work by default, starting from django-cors-headers up to django-ratelimit.

We also provide Middleware wrapper tools to convert any middleware response to the required API schema and set needed Content-Type, etc.

We support all existing mixins: because Controller is a subclass of Django’s django.views.generic.base.View class.

We support all existing decorators: because we have endpoint_decorator() and dispatch_decorator() utilities that can decorate endpoints and controllers.

Works best with django-stubs. Read next: our Integrations guide.

Next up¶

Using Controller

Learn how controllers work.

Using controller

Configuration

Learn how to configure django-modern-rest.

Configuration