mitodl/agent-kit/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

Resources

• Write Performant APIs - the handbook page this skill is drawn from
• 2026-03-24 MIT Learn outage post-mortem - what an expensive count query costs in production
• django-prefetch, django-zeal, mitol-drf-lint
• DRF: Pagination, Django: `prefetch_related()`, Django: `Prefetch` objects, Django: `cached_property`