# Django REST framework

![Logo by Jake 'Sid' Smith](https://github.com/encode/django-rest-framework/raw/master/docs/img/logo.png)

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

Некоторые причины, по которым вы можете захотеть использовать REST framework:

* Web-интерфейс API - огромный выигрыш в удобстве использования для ваших разработчиков.
* [Политики аутентификации](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/authentication), включая пакеты для [OAuth1a](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/navigaciya-po-api/authentication#django-rest-framework-oauth) и [OAuth2](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/navigaciya-po-api/authentication#django-oauth-toolkit).
* [Сериализация](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/serializers), поддерживающая как [ORM](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/navigaciya-po-api/serializers#modelserializer), так и [non-ORM](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/navigaciya-po-api/serializers#сериализаторы) источники данных.
* Настраивается все - просто используйте [обычные представления на основе функций](https://github.com/ilyachch/django-rest-framework-rusdoc/blob/master/api-guide/views/README.md#%D0%9F%D1%80%D0%B5%D0%B4%D1%81%D1%82%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F-%D0%BD%D0%B0-%D0%BE%D1%81%D0%BD%D0%BE%D0%B2%D0%B5-%D1%84%D1%83%D0%BD%D0%BA%D1%86%D0%B8%D0%B9), если вам не нужны [более](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/generic-views) [мощные](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/viewsets) [возможности](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/routers).
* Обширная документация и [отличная поддержка сообщества](https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework).
* Используется и пользуется доверием всемирно известных компаний, включая [Mozilla](https://www.mozilla.org/en-us/about/), [Red Hat](https://www.redhat.com/), [Heroku](https://www.heroku.com/) и [Eventbrite](https://www.eventbrite.co.uk/about/).

***

## Требования

REST framework требует следующего:

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

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

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

* [PyYAML](https://pypi.org/project/pyyaml/), [uritemplate](https://pypi.org/project/uritemplate/) (5.1+, 3.0.0+) - Поддержка генерации схем.
* [Markdown](https://pypi.org/project/markdown/) (3.3.0+) - Поддержка Markdown для Web-интерфейса API.
* [Pygments](https://pypi.org/project/pygments/) (2.7.0+) - Добавление подсветки синтаксиса в обработку Markdown.
* [django-filter](https://pypi.org/project/django-filter/) (1.0.1+) - Поддержка фильтрации.
* [django-guardian](https://github.com/django-guardian/django-guardian) (1.1.1+) - Поддержка разрешений на уровне объектов.

## Установка

Установите с помощью `pip`, включая все дополнительные пакеты, которые вы хотите...

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

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

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

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

```python
INSTALLED_APPS = [
    ...
    'rest_framework',
]
```

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

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

Обратите внимание, что путь URL может быть любым, какой вы захотите.

## Пример

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

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

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

```python
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`:

```python
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. Если вы используете элемент управления входом в систему в правом верхнем углу, вы также сможете добавлять, создавать и удалять пользователей из системы.

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

Не можете дождаться начала работы? Руководство [quickstart](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/quickstart) - это самый быстрый способ начать работу и создавать API с помощью REST framework.

## Руководство

Руководство проведет вас через все этапы настройки DRF. Это займет не очень много времени, однако вы получите полное понимание того, как все компоненты работают друг с другом и данное руководство крайне рекомендовано к прочтению.

* [Сериализация](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/quickstart/1-serialization)
* [Запросы-ответы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/quickstart/2-requests-and-responses)
* [Представления-классы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/quickstart/3-class-based-views)
* [Аутентификация/права доступа](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/quickstart/4-authentication-and-permissions)
* [Отношения и связи](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/quickstart/5-relationships-and-hyperlinked-apis)
* [Наборы представлений и роутеры](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/quickstart/6-viewsets-and-routers)

Так же есть пример работающего API законченного руководства для тестовых целей, [доступен здесь](http://restframework.herokuapp.com/).

## Навигатор по API

Навигатор по API - исчерпывающее руководство по всему функционалу, предоставляемому DRF.

* [Запросы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/requests)
* [Ответы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/responses)
* [Представления](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/views)
* [Общие представления](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/generic-views)
* [Viewsets](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/viewsets)
* [Маршрутизаторы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/routers)
* [Парсеры](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/parsers)
* [Рендереры](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/renderers)
* [Сериализаторы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/serializers)
* [Поля сериализатора](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/fields)
* [Отношения сериализаторов](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/relations)
* [Валидаторы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/validators)
* [Аутентификация](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/authentication)
* [Разрешения](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/permissions)
* [Кэширование](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/caching)
* [Дросселирование](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/throttling)
* [Фильтрация](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/filtering)
* [Пагинация](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/pagination)
* [Версионирование](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/versioning)
* [Согласование контента](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/content-negotiation)
* [Метаданные](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/metadata)
* [Schemas](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/schemas)
* [Cуффиксы формата](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/format-suffixes)
* [Возвращение URL-адресов](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/reverse)
* [Исключения](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/exceptions)
* [Коды состояния](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/status-codes)
* [Тестирование](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/testing)
* [Настройки](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/settings)

## Статьи

Основные руководства для использующих DRF.

* [AJAX, CSRF & CORS](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/ajax-csrf-cors)
* [The Browsable API](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/browsable-api)
* [Улучшения в браузере](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/browser-enhancements)
* [Документирование вашего API](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/documenting-your-api)
* [HTML и формы](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/html-and-forms)
* [Интернационализация](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/internationalization)
* [REST, гипермедиа и HATEOAS](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/rest-hypermedia-hateoas)
* [Вложенные сериализаторы с возможностью записи](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/stati/topics/writable-nested-serializers)

## Разработка

Смотрите [руководство для разработчиков](https://www.django-rest-framework.org/community/contributing/) для получения информации о том, как клонировать репозиторий, запустить набор тестов и внести изменения в REST Framework.

## Поддержка

За поддержкой обращайтесь в [REST framework discussion group](https://groups.google.com/forum/?fromgroups#!forum/django-rest-framework), попробуйте использовать канал `#restframework` на `irc.libera.chat`, или задайте вопрос на [Stack Overflow](https://stackoverflow.com/), обязательно указав тег ['django-rest-framework'](https://stackoverflow.com/questions/tagged/django-rest-framework).

Для получения приоритетной поддержки подпишитесь на [профессиональный или премиум спонсорский план](https://fund.django-rest-framework.org/topics/funding/).

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

Вопросы безопасности решаются под руководством [Django security team](https://www.djangoproject.com/foundation/teams/#security-team).

**Пожалуйста, сообщайте о проблемах безопасности по электронной почте <security@djangoproject.com>**.

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

***

## Авторы перевода

* [Ilya Chichak](https://github.com/ilyachch/)

## Помощь в переводе

* <https://github.com/pymq>
* <https://github.com/rufatpro>
* [Dmitry Plaxunov](https://github.com/fojetin)

Спасибо всем за помощь в переводе!

Перевод производится с помощью утилиты [md\_docs-trans-app](https://github.com/ilyachch/md_docs-trans-app)