Перейти к содержимому
Учи.Онлайн Выбрать школу
Статья

Django REST Framework: API на Django — сериализаторы, права, пагинация и документация

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

Автор: редакция Учи.ОнлайнОтветственный редактор: Дмитрий Игнатьев
Содержание
Иллюстрация к статье: Django REST Framework: API на Django — сериализаторы, права, пагинация и документация

Сам 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 придётся читать с поправкой.

  1. Сериализатор: поля, проверка, вложенные объекты, запись через create и update.
  2. Представления: APIView, generic-классы, ViewSet и роутер.
  3. Вход и права: сессия, токен, свой класс прав, фильтрация get_queryset.
  4. Пагинация, фильтры, сортировка, версия в адресе.
  5. Тесты на APITestCase, проверка числа запросов.
  6. Схема OpenAPI через drf-spectacular.

Первые шаги удобно пройти по официальному учебнику на django-rest-framework.org: в нём быстрый старт и шесть частей, которые ведут от сериализатора до ViewSet. Если нужна программа, где DRF стоит внутри общего пути Python-бэкенда, посмотрите онлайн-курс ProductStar «Python-разработчик»: шесть месяцев, блок «Бэкенд на Django» из пяти заданий с Django REST Framework, тестированием API, аутентификацией и OAuth 2.0. Как проверяют задания, стоит уточнить у школы.

Открыть курс «Python-разработчик»

Упражнения и типичные ошибки

Тренируйтесь на своей Django-модели. Сделайте только чтение, затем запись с проверкой полей, затем права «автор правит, остальные читают» на IsAuthenticatedOrReadOnly и своём классе. Включите пагинацию и откройте список под вторым пользователем.

Проверяйте себя как злоумышленник: запрос без токена, чужой идентификатор в адресе и в теле, пустое обязательное поле, пятитысячная страница. Ответ каждый раз должен быть ожидаемым: 401 или 403, 404, 400 с понятным текстом. Ещё одна частая ошибка — бизнес-логика в представлении вместо сериализатора или сервисного слоя.

Если нужен большой проект, где DRF — основа, подойдёт онлайн-курс Нетологии «Python-разработчик: расширенный курс»: двенадцать месяцев, Django REST framework в программе, а дипломная работа — бэкенд сервиса закупок для торговой сети с импортом каталога, корзиной, адресом доставки и уведомлениями по почте. Интерфейс необязателен, а Celery и Docker Compose для зачёта базовой части не нужны.

Открыть курс «Python-разработчик: расширенный курс»

Как навык влияет на доход

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.

Открыть курс «Профессия Python-разработчик»

Перед покупкой проведите вечер с официальным учебником: если ViewSet с роутером заработал и понятно, зачем фильтровать список отдельно от прав на объект, базы хватает для углублённой программы.

Сравнить школы по формату, поддержке и цене можно в рейтинге онлайн-школ с обучением Django — он шире DRF и охватывает весь фреймворк, поэтому отдельный модуль про API ищите уже в программе выбранного курса.