Routing¶

Our Controller is built without knowing anything about its future URL. Why so?

Because Django already has an amazing URL routing system and we don’t need to duplicate it
Because all controllers might be used in multiple URLs, for example in /api/v1/ and /api/v2/. Our design allows any possible customizations

views.py¶

from django.urls import include

# Our `path` is an optimized drop-in replacement of `django.urls.path`:
from dmr.routing import Router, path
from examples.getting_started.pydantic_controller import UserController

# Router is just a collection of regular Django urls:
router = Router(
    'api/',
    [
        path(
            'user/',
            UserController.as_view(),
            name='users',
        ),
    ],
)

# Just a regular `urlpatterns` definition, Django-style:
urlpatterns = [
    path(router.prefix, include((router.urls, 'rest_app'), namespace='api')),
]

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json' -H 'X-API-Consumer: my-api'
{"email":"user@wms.org","uid":"4cfb07df-ab0d-49d4-9323-759db9ea3e44"}

Note

If you want to parse path parameters, see Path parameters and dmr.components.Path.

Handling 404 errors¶

By default, Django returns HTML 404 pages. This is not what we want for API endpoints. Instead, we want to return API responses with proper error structure and content negotiation (e.g. JSON or XML based on the Accept header).

But, we still want HTML 404 pages for non API views.

Important

Overriding django.conf.urls.handler404 has no effect while DEBUG = True is set.

This is how Django behaves: https://docs.djangoproject.com/en/stable/ref/views/#the-404-page-not-found-view

To achieve this, you can use build_404_handler() helper. It creates a handler that returns API-style 404 responses for specific path prefixes (using the same serializer and renderers as your API), and falls back to Django’s default handler for everything else.

Here is how you can use it in your root urls.py (in your ROOT_URLCONF):

urls.py¶

[source]

import pydantic
from django.urls import include

from dmr import Body, Controller
from dmr.plugins.pydantic import PydanticSerializer
from dmr.routing import Router, build_404_handler, path


class UserCreateModel(pydantic.BaseModel):
    email: str


class UserController(
    Controller[PydanticSerializer],
):
    async def post(self, parsed_body: Body[UserCreateModel]) -> UserCreateModel:
        return parsed_body


router = Router(
    'api/',
    [
        path('user/', UserController.as_view(), name='users'),
    ],
)

urlpatterns = [
    path(router.prefix, include((router.urls, 'your_app'), namespace='api')),
]

handler404 = build_404_handler(router.prefix, serializer=PydanticSerializer)

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "correct@example.com"}' -H 'Content-Type: application/json'
{"email":"correct@example.com"}

$ curl http://127.0.0.1:8000/api/wrong/ -D - -X POST -d '{"email": "correct@old-domain.com"}' -H 'Content-Type: application/json'
HTTP/1.1 404 Not Found
date: Sun, 29 Mar 2026 18:53:09 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 56
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Page not found","type":"not_found"}]}

This returns json responses for api/ prefixed paths. But, will still return regular Django HTML responses for any other path.

Handling 500 errors¶

By default, Django returns HTML 500 pages. This is not what we want for API endpoints. Instead, we want to return API responses with proper error structure and content negotiation (e.g. JSON or XML based on the Accept header).

But, we still want HTML 500 pages for non API views.

Important

Overriding django.conf.urls.handler500 has no effect while DEBUG = True is set.

This is how Django behaves: https://docs.djangoproject.com/en/stable/ref/views/#the-500-server-error-view

To achieve this, you can use build_500_handler() helper. It creates a handler that returns API-style 500 responses for specific path prefixes (using the same serializer and renderers as your API), and falls back to Django’s default handler for everything else.

Here is how you can use it in your root urls.py (in your ROOT_URLCONF):

views.py¶

[source]

import pydantic
from django.urls import include

from dmr import Body, Controller
from dmr.plugins.pydantic import PydanticSerializer
from dmr.routing import Router, build_500_handler, path


class UserCreateModel(pydantic.BaseModel):
    email: str


class UserController(
    Controller[PydanticSerializer],
):
    async def post(self, parsed_body: Body[UserCreateModel]) -> UserCreateModel:
        if 'old-domain.com' in parsed_body.email:
            raise RuntimeError('This error will not be handled')
        return parsed_body


router = Router(
    'api/',
    [
        path('user/', UserController.as_view(), name='users'),
    ],
)

urlpatterns = [
    path(router.prefix, include((router.urls, 'your_app'), namespace='api')),
]

handler500 = build_500_handler(router.prefix, serializer=PydanticSerializer)

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "correct@example.com"}' -H 'Content-Type: application/json'
{"email":"correct@example.com"}

$ curl http://127.0.0.1:8000/api/user/ -D - -X POST -d '{"email": "correct@old-domain.com"}' -H 'Content-Type: application/json'
HTTP/1.1 500 Internal Server Error
date: Sun, 29 Mar 2026 18:53:09 GMT
server: uvicorn
Content-Type: application/json
X-Frame-Options: DENY
Vary: Accept-Language
Content-Language: en
Content-Length: 68
X-Content-Type-Options: nosniff
Referrer-Policy: same-origin
Cross-Origin-Opener-Policy: same-origin

{"detail":[{"msg":"Internal server error","type":"internal_error"}]}

Optimized URL Routing¶

django-modern-rest provides an optimized dmr.routing.path() function that is a drop-in replacement for Django’s django.urls.path().

The custom implementation uses prefix-based pattern matching for faster routing. Instead of immediately running Django’s regex engine on every request, it performs a quick prefix check first.

Performance Impact¶

Benchmark results on MacBook Pro M4 Pro:

Best case: 9% faster (match found in first few URL patterns)
Average case: 13% faster (match found in middle of URL patterns list)
Worst case: 31% faster (404 Not Found, all patterns checked)

The prefix-based optimization dramatically reduces regex operations:

Static routes: Simple string comparison (no regex at all)
Dynamic routes: Regex only runs when prefix matches
Failed matches: Eliminated in one operation (startswith check)

This is especially beneficial for applications with:

Large number of routes
High traffic

Migration¶

Simply replace Django’s path with dmr.routing.path():

# Instead of ``from django.urls import path``:
from dmr.routing import path
from django.urls import include

urlpatterns = [
    path('api/', include('myapp.urls')),
]

This is a drop-in replacement with no API changes required.