drf-api-performance

Performant DRF APIs

A fast API is two problems: the shape of the response, and the cost of the queries that fill it. These rules apply to every DRF viewset, serializer, and queryset.

The rules

• Keep response nesting to two levels or less; split deeper data into a second endpoint.
• Paginate every list endpoint. Set the default once in a shared module, cap client-supplied page size with max_limit, and order deterministically.
• Narrow the pagination count query to the primary key. It is a second query over your whole result set, and it scales with production data, not fixtures.
• Pick the narrowest prefetch tool that works: select_related() for foreign keys, prefetch_related() for to-many relationships, prefetch() for data the model has no direct relationship to.
• Use select_related(), not prefetch_related(), when the queryset already filters or orders on that table - the join is happening either way.
• Three or four to-one joins are fine; treat eight as the review threshold where you check EXPLAIN and split the query instead of widening it further.
• Never query inside a serializer or call a function directly or indirectly that makes one - the body runs once per object, so a query there is multiplied by the page size. The view's queryset assembles the data.
• Declare required_prefetches on every serializer. It fails loudly under DEBUG and pytest; in production it only logs, so treat it as a development guardrail and not a reason to skip the prefetch.
• Back a prefetch with a same-named cached_property so non-API callers get the same answer without a second implementation.
• Test list APIs with 5-10 records at each level, or the N+1 checks won't fire.
• Pin a constant query count across varying data with django_assert_num_queries, and never add skip_nplusone_check to a new test.

References