Django REST framework

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

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

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

Зависимости

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

• Python (2.7, 3.2, 3.3, 3.4, 3.5, 3.6)
• Django (1.8, 1.9, 1.10, 1.11)

Данные пакеты не обязательны:

• coreapi (1.32.0+) - Schema generation support.
• Markdown (2.1.0+) - Markdown support for the browsable API.
• django-filter (1.0.1+) - Filtering support.
• django-crispy-forms - Improved HTML display for filtering.
• django-guardian (1.1.1+) - Object level permissions support.

Установка

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

pip install djangorestframework
pip install markdown        # Опционально
pip install django-filter   # Опционально

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

git clone [email protected]:encode/django-rest-framework.git

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

INSTALLED_APPS = (
    ...
    'rest_framework',
)

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

urlpatterns = [
    ...
    url(r'^api-auth/', include('rest_framework.urls',namespace='rest_framework'))
]

Важно помнить, что в качестве пути вы можете указать что угодно, однако подключить необходимо rest_framework.urls с указанием пространства имен rest_framework. Но в Django версии 1.9 и выше, пространство имен можно оставить пустым и DRF заполнит его за вас.

Пример

Давайте рассмотрим небольшой пример использования DRF для построения основанного на моделях API.

Мы создадим API с возможностью чтения/записи и доступом к данным пользователей нашего проекта.

Любые глобальные настройки DRF описываются в словаре конфигурации 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.

Ниже представлен корневой диспетчер URL:

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

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

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

Руководство

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

1. Сериализация
2. Запросы-ответы
3. Представления-классы
4. Аутентификация/права доступа
5. Отношения и связи
6. Наборы представлений и роутеры
7. Схемы и клиентские библиотеки

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

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

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

• Запросы
• Ответы
• Представления
• Общие представления
• Viewsets
• Маршрутизаторы
• Парсеры
• Рендеры
• Cериализаторы
• Serializer fields
• Serializer relations
• Validators
• Authentication
• Permissions
• 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]. Руководители проекта будут работать с вами для решения любых подобных проблем.