Django REST framework (DRF) - мощный и гибкий инструмент для построения Web API.

Вот несколько причин, чтобы использовать DRF:

• Крайне удобная для разработчиков браузерная версия API;

• Наличие пакетов для OAuth1a и OAuth2 авторизации;

• Сериализация, поддерживающая ORM и не-ORM источники данных;

• Возможность полной и детальной настройки - можно использовать обычные представления-функции, если вы не нуждаетесь в мощном функционале;

• Расширенная документация и отличная поддержка сообщества;

• Используется и пользуется уважением таких узнаваемых компаний, как Mozilla, Red Hat, Heroku, Eventbrite.

Существует пример API для тестирования, который доступен здесь доступно здесь.

Зависимости

У DRF следующие требования:

• Python (3.5, 3.6, 3.7)

• Django (1.11, 2.0, 2.1, 2.2)

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

Установка

Установите с помощью pip

pip install djangorestframework

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

INSTALLED_APPS = (
    ...
    'rest_framework',
)

Пример

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

Запустите новый проект, как ...

pip install django
pip install djangorestframework
django-admin startproject example .
./manage.py migrate
./manage.py createsuperuser

Теперь отредактируйте модуль example/urls.py в вашем проекте:

from django.conf.urls import url, include
from django.contrib.auth.models import User
from rest_framework import routers, serializers, viewsets
​
# Сериализаторы описывают представление данных.
class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'is_staff']
​
# Наборы представлений описывают поведение представлений.
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
​
# Роутеры позволяют быстро и просто сконфигурировать адреса.
router = routers.DefaultRouter()
router.register(r'users', UserViewSet)
​
# Привяжите конфигурацию URL, используя роутеры.
# Так же мы предоставляем URL для авторизации в браузере.
urlpatterns = [
    url(r'^', include(router.urls)),
    url(r'^api-auth/', include('rest_framework.urls', namespace='rest_framework'))
]

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

Добавьте следующее к вашему settings.py модулю:

INSTALLED_APPS = [
    ...  # Убедитесь, что здесь включены установленные по умолчанию приложения.
    'rest_framework',
]
​
REST_FRAMEWORK = {
    # Используйте стандартные Django  `django.contrib.auth` разрешения,
    # или разрешите доступ только для чтения для неаутентифицированных пользователей.
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.DjangoModelPermissionsOrAnonReadOnly'
    ]
}

Вот и все, мы закончили!

./manage.py runserver

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

Вы также можете взаимодействовать с API с помощью инструментов командной строки, таких как curl. Например, чтобы вывести конечную точку пользователей:

$ curl -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/
[
    {
        "url": "http://127.0.0.1:8000/users/1/",
        "username": "admin",
        "email": "[email protected]",
        "is_staff": true,
    }
]

Или создать нового пользователя:

$ curl -X POST -d username=new -d [email protected] -d is_staff=false -H 'Accept: application/json; indent=4' -u admin:password http://127.0.0.1:8000/users/
{
    "url": "http://127.0.0.1:8000/users/2/",
    "username": "new",
    "email": "[email protected]",
    "is_staff": false,
}

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

Не можете дождаться, чтобы начать? Руководство по быстрому старту - быстрейший способ.

Руководство

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

1. ​Сериализация​

2. ​Запросы-ответы​

3. ​Представления-классы​

4. ​Аутентификация/права доступа​

5. ​Отношения и связи​

6. ​Наборы представлений и роутеры​

7. ​Схемы и клиентские библиотеки​

Так же есть пример работающего API законченного руководства для тестовых целей, доступен здесь.

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

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

• ​Запросы​

• ​Ответы​

• ​Представления​

• ​Общие представления​

• ​Viewsets​

• ​Маршрутизаторы​

• ​Парсеры​

• ​Рендеры​

• ​Cериализаторы​

• ​Serializer fields​

• ​Serializer relations​

• ​Validators​

• ​Authentication​

• ​Permissions​

• ​Caching​

• ​Throttling​

• ​Filtering​

• ​Pagination​

• ​Versioning​

• ​Content negotiation​

• ​Metadata​

• ​Schemas​

• ​Format suffixes​

• ​Returning URLs​

• ​Exceptions​

• ​Status codes​

• ​Testing​

• ​Settings​

Статьи

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

• ​Documenting your API​

• ​API Clients​

• ​Internationalization​

• ​AJAX, CSRF & CORS​

• ​HTML & Forms​

• ​Browser enhancements​

• ​The Browsable API​

• ​REST, Hypermedia & HATEOAS​

• ​Third Party Packages​

• ​Tutorials and Resources​

• ​Contributing to REST framework​

• ​Project management​

• ​3.0 Announcement​

• ​3.1 Announcement​

• ​3.2 Announcement​

• ​3.3 Announcement​

• ​3.4 Announcement​

• ​3.5 Announcement​

• ​3.6 Announcement​

• ​Kickstarter Announcement​

• ​Mozilla Grant​

• ​Funding​

• ​Release Notes​

• ​Jobs​

Разработка

Прочтите руководство для разработчиков для получения информации о том, как склонировать репозиторий, запустить набор тестов и отправить изменения обратно в DRF.

Поддержка

Для поддержки обратитесь в группу обсуждения DRF или создайте вопрос на StackOverflow с указанием тэга 'django-rest-framework'.

Для уведомления об обновлениях, подпишитесь на нас в Twitter.

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

Если вы уверены, что нашли пробел в безопасности, пожалуйста, не создавайте публичный баг-репорт!

Отправьте описание проблемы по почте [email protected]. Руководители проекта будут работать с вами для решения любых подобных проблем.

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

• ​Ilya Chichak​

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

• ​https://github.com/pymq​

• ​https://github.com/rufatpro​

• ​Dmitry Plaxunov​

Пожалуйста, открывая Pull Request, указывайте меня в качестве ревьюера, так я буду узнавать об этом моментально.

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

Перевод производится с помощью утилиты md_docs-trans-app​