# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.