Django REST Framework

Django REST framework — это мощный и гибкий инструмент для создания веб-API.

Вот несколько причин, по которым вам может понадобиться REST framework:

Веб-браузерный API — это огромный выигрыш в удобстве для ваших разработчиков.
Политики аутентификации, включая пакеты для OAuth1a и OAuth2.
Сериализация, которая поддерживает как ORM, так и не-ORM источники данных.
Настраиваемость на всех уровнях — просто используйте обычные представления на основе функций, если вам не нужны более мощные функции маршрутизатора.
Обширная документация и отличная поддержка сообщества.
Используется и доверяется международными компаниями, включая Mozilla, Red Hat, Heroku и Eventbrite.

Финансирование

REST framework — это совместно финансируемый проект. Если вы используете REST framework в коммерческих целях, мы настоятельно рекомендуем вам инвестировать в его дальнейшее развитие, подписавшись на платный план.

Каждая подписка помогает нам сделать REST framework долгосрочно финансово устойчивым.

Большое спасибо всем нашим прекрасным спонсорам, а также нашим премиум-подписчикам, Sentry, Stream, Spacinov, Retool, bit.io, PostHog, CryptAPI, FEZTO, Svix и Zuplo.

Требования

REST framework требует следующих компонентов:

Django (4.2, 5.0)
Python (3.8, 3.9, 3.10, 3.11, 3.12)

Мы настоятельно рекомендуем и официально поддерживаем только последние исправления каждой серии Python и Django.

Следующие пакеты являются необязательными:

PyYAML, uritemplate (5.1+, 3.0.0+) — поддержка генерации схем.
Markdown (3.3.0+) — поддержка Markdown для веб-браузерного API.
Pygments (2.7.0+) — добавление подсветки синтаксиса к обработке Markdown.
django-filter (1.0.1+) — поддержка фильтрации.
django-guardian (1.1.1+) — поддержка разрешений на уровне объектов.

Установка

Установите с помощью pip, включая любые необязательные пакеты, которые вам нужны...

pip install djangorestframework
pip install markdown       # Markdown support for the browsable API.
pip install django-filter  # Filtering support

...или клонируйте проект с GitHub.

git clone https://github.com/encode/django-rest-framework

Добавьте 'rest_framework' в настройки INSTALLED_APPS.

INSTALLED_APPS = [
    ...
    'rest_framework',
]

Если вы планируете использовать веб-браузерный API, вам, вероятно, также потребуется добавить представления REST framework для входа и выхода. Добавьте следующее в ваш файл root urls.py.

urlpatterns = [
    ...
    path('api-auth/', include('rest_framework.urls'))
]

Обратите внимание, что путь к URL-адресу может быть любым.

Пример

Давайте рассмотрим быстрый пример использования REST framework для создания простого API, основанного на модели.

Мы создадим API для чтения и записи информации об пользователях нашего проекта.

Все глобальные настройки для API REST framework хранятся в одном словаре настроек с именем REST_FRAMEWORK. Начните с добавления следующего в свой модуль settings.py.

REST_FRAMEWORK = {
    # Use Django's standard `django.contrib.auth` permissions,
    # or allow read-only access for unauthenticated users.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
    ]
}

Не забудьте также добавить rest_framework в свой модуль INSTALLED_APPS.

Теперь мы готовы создать наш API. Вот корневой модуль проекта urls.py.

from django.urls import path, include
from django.contrib.auth.models import User
from rest_framework import routers, serializers, viewsets

# Serializers define the API representation.
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'is_staff']

# ViewSets define the view behavior.
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

# Routers provide an easy way of automatically determining the URL conf.
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)

# Wire up our API using automatic URL routing.
# Additionally, we include login URLs for the browsable API.
urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

Теперь вы можете открыть API в браузере по адресу http://127.0.0.1:8000/ и просмотреть новый API «users». Если вы воспользуетесь панелью входа в правом верхнем углу, вы также сможете добавлять, создавать и удалять пользователей из системы.

Быстрый старт

Не можете дождаться начала? Руководство быстрого старта — это самый быстрый способ начать работу и создавать API с помощью REST framework.

Разработка

См. руководство по внесению изменений для получения информации о том, как клонировать репозиторий, запустить набор тестов и помочь в обслуживании кода REST Framework.

Поддержка

Для получения поддержки посетите группу обсуждения REST framework, попробуйте канал #restframework в irc.libera.chat, или задайте вопрос на Stack Overflow, обязательно включив тег 'django-rest-framework'.

Для приоритетной поддержки подпишитесь на профессиональный или премиум-пакет спонсорства.

Безопасность

Вопросы безопасности рассматриваются под руководством команды безопасности Django.

Пожалуйста, сообщайте о проблемах безопасности, написав письмо по адресу security@djangoproject.com.

Авторы проекта затем будут работать с вами над решением любых проблем, прежде чем они станут достоянием общественности.

Лицензия

Перераспределение и использование в исходной и двоичной формах, с изменениями или без них, разрешено при соблюдении следующих условий:

При перераспределении исходного кода необходимо сохранить вышеуказанное уведомление об авторском праве, этот список условий и следующее уведомление об отказе от гарантий.
При перераспределении в двоичной форме необходимо воспроизвести вышеуказанное уведомление об авторском праве, этот список условий и следующее уведомление об отказе от гарантий в документации и/или других материалах, поставляемых с дистрибутивом.
Имя правообладателя или имена его авторов не могут использоваться для поддержки или продвижения продуктов, полученных из этого программного обеспечения, без предварительного письменного разрешения.

ЭТО ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ ПРАВООБЛАДАТЕЛЯМИ И АВТОРАМИ «КАК ЕСТЬ», И ЛЮБЫЕ ЯВНЫЕ ИЛИ ПОДРАЗУМЕВАЕМЫЕ ГАРАНТИИ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ГАРАНТИЯМИ ТОВАРНОЙ ПРИГОДНОСТИ И ПРИГОДНОСТИ ДЛЯ КОНКРЕТНОЙ ЦЕЛИ, ОТКАЗЫВАЮТСЯ. НИ В КОЕМ СЛУЧАЕ ПРАВООБЛАДАТЕЛЬ ИЛИ АВТОРЫ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ПРЯМЫЕ, КОСВЕННЫЕ, СЛУЧАЙНЫЕ, СПЕЦИАЛЬНЫЕ, ИЗЛИШНИЕ ИЛИ СЛЕДСТВУЮЩИЕ УБЫТКИ (ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ ПОКУПКОЙ ЗАМЕНИТЕЛЬНЫХ ТОВАРОВ ИЛИ УСЛУГ; ПОТЕРЯ ИСПОЛЬЗОВАНИЯ, ДАННЫХ ИЛИ ПРИБЫЛИ; ИЛИ ПРЕКРАЩЕНИЕ ДЕЯТЕЛЬНОСТИ), ПРИЧИНЫ И ПО КАКУЮ ЛИБО ТЕОРИЮ ОТВЕТСТВЕННОСТИ, ЧТО ИНОГДА ЛИБО В ДОГОВОРЕ, СТРОГОЙ ОТВЕТСТВЕННОСТИ ИЛИ ДЕЛИКТА (ВКЛЮЧАЯ НЕБРЕЖНОСТЬ ИЛИ ИНАЧЕ), ВОЗНИКШИЕ ЛЮБЫМ ОБРАЗОМ ИЗ ИСПОЛЬЗОВАНИЯ ЭТОГО ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ, ДАЖЕ ЕСЛИ БЫЛО ОБЪЯВЛЕНО О ВОЗМОЖНОСТИ ТАКИХ УБЫТКОВ.