Routing#

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

  1. Because Django already has an amazing URL routing system and we don’t need to duplicate it

  2. Because all controllers might be used in multiple URLs, for example in /api/v1/ and /api/v2/. Our design allows any possible customizations

Run result

$ curl http://127.0.0.1:8000/api/user/ -X POST -d '{"email": "user@wms.org"}' -H 'Content-Type: application/json'
{"email":"user@wms.org","uid":"1c761260-9f6b-42fa-acc2-d77ebc99ac75"}

Notice our helper method to_urlpatterns(). It can be used directly, or if some users prefer, it can be replaced with a raw path() call:

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

Which is semantically identical.

Note

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

Including routers from other apps#

Added in version 0.13.0.

It is common in Django to use multiple apps with their own URLs and views. They might define their own Router instances, which can be included into the main router.

To do so, use the include() method:

It automatically uses our own faster path() function. Basically, including another router is the same as writing:

router = Router(
    prefix='api/',
    urls=[
        path(
            other.router.prefix,
            include(
                (other_router.router.urls, 'app_name'),
                namespace='namespace',
            ),
        ),
    ],
)

Use it to reduce boilerplate code. You can also use to_urlpatterns() if you prefer. It is semantically identical, except for the metadata. include correctly handles nested metadata like tags, deprecated and ignore_from_spec, while using to_urlpatterns ignores it. So, if you don’t use the router-level metadata, it does not matter which one you use.

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 the build_404_handler() helper. It creates a handler that returns API-style 404 responses for specific path prefixes (using the same serializer and renderer 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):

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: Wed, 07 Oct 2026 07:03:56 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 the build_500_handler() helper. It creates a handler that returns API-style 500 responses for specific path prefixes (using the same serializer and renderer 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):

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: Wed, 07 Oct 2026 07:03:57 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"}]}

See also

See Error handling if you want to learn how to handle different errors based on different levels and fix these 500 exceptions.

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 a MacBook Pro M4 Pro:

  • Best case: 9% faster (match found in the first few URL patterns)

  • Average case: 13% faster (match found in the 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 the 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.

External views#

django-modern-rest can include URLs from other frameworks. It can also reuse an existing OpenAPI schema giving you the most freedom possible.

If you need this advanced feature, see the External views guide.