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 git@github.com: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. Это займет не очень много времени, однако вы получите полное понимание того, как все компоненты работают друг с другом и данное руководство крайне рекомендовано к прочтению.
- Сериализация
- Запросы-ответы
- Представления-классы
- Аутентификация/права доступа
- Отношения и связи
- Наборы представлений и роутеры
- Схемы и клиентские библиотеки
Так же есть пример работающего 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.
Если вы уверены, что нашли пробел в безопасности, пожалуйста, не создавайте публичный баг-репорт!
Отправьте описание проблемы по почте rest-framework-security@googlegroups.com. Руководители проекта будут работать с вами для решения любых подобных проблем.