Django REST Framework: API на Django — сериализаторы, права, пагинация и документация
Django REST Framework (DRF) — библиотека, которая превращает модели Django в API: сервер отдаёт мобильному приложению, фронтенду или другому сервису данные в JSON, а не HTML-страницы. Разработчик описывает сериализатор — какие поля модели уходят наружу и как проверять входящие данные, — ViewSet с набором действий и роутер, который сам строит адреса. Сверху настраиваются вход, права, пагинация, фильтры, версии и документация OpenAPI. Для старта нужен уверенный Django: модели, ORM и миграции.
Содержание

Сам Django остаётся за кадром, ему посвящён отдельный материал; здесь речь о слое между HTTP-запросом и строкой в базе. Частое заблуждение новичков — раз DRF «из коробки» умеет почти всё, то и безопасен он по умолчанию. Это не так: ниже разобраны две настройки, которые чаще всего оставляют API открытым.
Что делает DRF и когда он не нужен
Типичная задача: у компании уже есть сайт на Django, и понадобилось мобильное приложение или фронтенд на React. DRF отдаёт те же данные по API без переписывания проекта: сериализатор переводит объект модели в JSON и обратно, проверяет поля, а ViewSet связывает это с запросами GET, POST, PATCH и DELETE. В браузере DRF показывает API как страницу с формами, где можно отправить запрос без Postman.
Для маленького сервиса без базы и пользователей, например вебхука, проще FastAPI, а для выборок произвольной формы рассматривают GraphQL — о них на сайте есть отдельные статьи. DRF выигрывает, когда в проекте уже есть модели Django, права пользователей и админка.
Учебный пример: API заявок на ремонт
Ситуация учебная. Сервисный отдел ведёт заявки на ремонт оборудования в Django-админке, а инженерам нужно мобильное приложение: создать заявку, увидеть свои, поправить заголовок. Модель Ticket уже есть: заголовок, статус, оборудование, автор, дата. Первый шаг — сериализатор:
from rest_framework import serializers
from .models import Ticket
class TicketSerializer(serializers.ModelSerializer):
author = serializers.ReadOnlyField(source="author.username")
class Meta:
model = Ticket
fields = ["id", "title", "status", "equipment", "author", "created_at"]
read_only_fields = ["status", "created_at"]
Список fields перечислен явно, а не через "__all__": иначе новое служебное поле модели само уйдёт в ответ API. Статус доступен только для чтения — менять его будет диспетчер в админке. Затем ViewSet и роутер:
from rest_framework import permissions, viewsets
from rest_framework.routers import DefaultRouter
class TicketViewSet(viewsets.ModelViewSet):
serializer_class = TicketSerializer
permission_classes = [permissions.IsAuthenticated]
def get_queryset(self):
return (Ticket.objects.filter(author=self.request.user)
.select_related("author", "equipment"))
def perform_create(self, serializer):
serializer.save(author=self.request.user)
router = DefaultRouter()
router.register("tickets", TicketViewSet, basename="ticket")
urlpatterns = router.urls
Роутер создаёт адреса /tickets/ для списка и создания и /tickets/<id>/ для просмотра, правки и удаления. Параметр basename здесь обязателен: у ViewSet нет атрибута queryset, и роутеру не из чего вывести имя. Метод perform_create подставляет автора из запроса, чтобы клиент не мог прислать чужой идентификатор.
Права: где API остаётся открытым
Главная ловушка описана в документации DRF о правах доступа. Если настройку DEFAULT_PERMISSION_CLASSES не задать, она равна AllowAny, то есть любой запрос без входа проходит. Поэтому её сразу переводят на IsAuthenticated, а открытые методы помечают явно.
Вторая ловушка тоньше. Допустим, разработчик пишет класс прав IsAuthor с методом has_object_permission и проверяет: чужая заявка по адресу /tickets/5/ отдаёт 403, всё работает. Но по документации такие проверки запускаются только при вызове get_object(), то есть для действий с одним объектом. К списку они не применяются: если get_queryset возвращает все заявки, /tickets/ покажет каждому чужие. При создании объекта has_object_permission тоже не вызывается, и ограничения нужно писать в сериализаторе или в perform_create. В учебном примере обе дыры закрыты фильтром в get_queryset и perform_create.
Вход настраивается отдельно от прав: браузерному клиенту на том же домене подходит сессия Django с CSRF-токеном, мобильному приложению — токен DRF или JWT через djangorestframework-simplejwt.
Пагинация, фильтры, версии и лимиты
По разделу о пагинации, DEFAULT_PAGINATION_CLASS и PAGE_SIZE по умолчанию равны None: список отдаётся целиком. На ста тысячах заявок такой запрос съест память сервера. PageNumberPagination с PAGE_SIZE = 20 закрывает вопрос для каталогов, а для ленты, куда постоянно добавляются записи, лучше CursorPagination: она требует уникального и неизменного порядка сортировки, зато клиент не увидит одну запись дважды. В APIView пагинацию вызывают вручную.
Фильтры по полям добавляет пакет django-filter (?status=open), поиск и сортировку — встроенные SearchFilter и OrderingFilter. Версию API чаще всего кладут в адрес (/api/v1/) через URLPathVersioning: старое мобильное приложение продолжает ходить по прежнему адресу, а новое — в /api/v2/. Ограничение частоты запросов (throttling) хранит счётчики в кеше Django, и документация прямо предупреждает: это не защита от перебора паролей и DoS-атак.
Документация OpenAPI через drf-spectacular
По разделу о схемах, встроенная в DRF генерация описания OpenAPI объявлена устаревшей и будет выведена из оборота, а заменой названа библиотека drf-spectacular. Она собирает схему из сериализаторов и ViewSet, а SpectacularSwaggerView показывает интерактивную страницу Swagger UI. Неочевидные ответы уточняют декоратором @extend_schema. О самом формате OpenAPI на сайте есть отдельная статья.
Тесты и лишние запросы к базе
Для API тесты особенно дёшевы: APITestCase и APIClient отправляют запрос и проверяют код ответа и JSON, а force_authenticate входит под нужным пользователем без пароля. Первый тест стоит написать на утечку из раздела о правах: два пользователя, у каждого заявка, и второй не должен видеть заявку первого в списке.
Вложенные объекты в сериализаторе незаметно умножают запросы к базе: автор и оборудование подтягиваются для каждой заявки отдельно. Это лечат select_related и prefetch_related в get_queryset, а проверяют тестом с assertNumQueries: число запросов не должно расти с длиной страницы.
С чего начать и в каком порядке осваивать
Порядок ниже выстроен так, чтобы каждый шаг давал работающий результат: сначала данные на своей машине, потом права и вход, затем то, что нужно настоящим клиентам. Версии стоит выбрать сразу: DRF 3.18 от 7 августа 2026 года прекратил поддержку Django 4.2, 5.0 и 5.1 и добавил 6.1, а версия 3.18.2 от 6 октября закрыла три уязвимости. Учебник на Django 4.2 придётся читать с поправкой.
- Сериализатор: поля, проверка, вложенные объекты, запись через
createиupdate. - Представления:
APIView, generic-классы, ViewSet и роутер. - Вход и права: сессия, токен, свой класс прав, фильтрация
get_queryset. - Пагинация, фильтры, сортировка, версия в адресе.
- Тесты на
APITestCase, проверка числа запросов. - Схема OpenAPI через drf-spectacular.
Первые шаги удобно пройти по официальному учебнику на django-rest-framework.org: в нём быстрый старт и шесть частей, которые ведут от сериализатора до ViewSet. Если нужна программа, где DRF стоит внутри общего пути Python-бэкенда, посмотрите онлайн-курс ProductStar «Python-разработчик»: шесть месяцев, блок «Бэкенд на Django» из пяти заданий с Django REST Framework, тестированием API, аутентификацией и OAuth 2.0. Как проверяют задания, стоит уточнить у школы.
Упражнения и типичные ошибки
Тренируйтесь на своей Django-модели. Сделайте только чтение, затем запись с проверкой полей, затем права «автор правит, остальные читают» на IsAuthenticatedOrReadOnly и своём классе. Включите пагинацию и откройте список под вторым пользователем.
Проверяйте себя как злоумышленник: запрос без токена, чужой идентификатор в адресе и в теле, пустое обязательное поле, пятитысячная страница. Ответ каждый раз должен быть ожидаемым: 401 или 403, 404, 400 с понятным текстом. Ещё одна частая ошибка — бизнес-логика в представлении вместо сериализатора или сервисного слоя.
Если нужен большой проект, где DRF — основа, подойдёт онлайн-курс Нетологии «Python-разработчик: расширенный курс»: двенадцать месяцев, Django REST framework в программе, а дипломная работа — бэкенд сервиса закупок для торговой сети с импортом каталога, корзиной, адресом доставки и уведомлениями по почте. Интерфейс необязателен, а Celery и Docker Compose для зачёта базовой части не нужны.
Как навык влияет на доход
DRF редко оплачивается отдельно: это строка в требованиях к Python-разработчику бэкенда. Среди первых десяти вакансий по запросу «Django REST Framework» на Хабр Карьере 15 октября 2026 года восемь были для Python-разработчиков и две для тестировщиков; семь из десяти — уровня middle.
Отдельной зарплатной статистики по DRF калькулятор Хабр Карьеры не даёт: с этим навыком в фильтре выборка не меняется. По калькулятору для бэкенд-разработчиков в октябре 2026 года медиана — 248 333 ₽ по 7 503 анкетам, у junior — 98 333 ₽ (904 анкеты), у middle — 215 833 ₽ (3 345), у senior — 346 666 ₽ (2 106). Это все регионы, анкеты за скользящие полгода по методике калькулятора, а не предложения в вакансиях. Разрыв между уровнями показывает, что платят не за DRF, а за опыт, базы данных и нагрузку.
Как выбрать обучение
DRF нужен Python-разработчикам бэкенда и fullstack, а также тестировщикам API, которые читают код сериализаторов. При выборе программы смотрите, есть ли в ней права на уровне объекта, пагинация, тесты API и документация, проверяет ли кто-нибудь код и на какой версии Django идут материалы.
Отсутствие DRF в описании ещё не значит, что его нет в программе. На онлайн-курсе Skillfactory «Профессия Python-разработчик» модуль «Python-фреймворк Django» рассчитан на 190 часов: модели и ORM, маршрутизация, шаблоны, формы, аутентификация и REST API с собственным проектом, а задания проверяют менторы. До оплаты спросите у школы, используют ли Django REST Framework и на чём строят REST API.
Перед покупкой проведите вечер с официальным учебником: если ViewSet с роутером заработал и понятно, зачем фильтровать список отдельно от прав на объект, базы хватает для углублённой программы.
Сравнить школы по формату, поддержке и цене можно в рейтинге онлайн-школ с обучением Django — он шире DRF и охватывает весь фреймворк, поэтому отдельный модуль про API ищите уже в программе выбранного курса.