BestDoctor's batteries for REST services.
Project description
RestDoctor
BestDoctor's batteries for REST services.
Для чего нужен RestDoctor
У нас в BestDoctor есть свой API Guide, в котором написано, как API должно быть построено. А еще у нас есть Django и довольно логично использовать Django Rest Framework. Он достаточно гибкий, однако в некоторых местах мы хотим получить больше контроля и соблюдения своих правил.
Поэтому мы написали свою надстройку над DRF, которая имеет
- Полную изоляцию между версиями API
- Версионирование через заголовок
Accept
- Декларативную настройку сериализаторов и классов разрешений для
View
иViewSet
- Прокачанную генерацию схемы
Установка
Добавляем пакет restdoctor
в зависимости или ставим через pip.
Добавляем настройки в Settings:
ROOT_URLCONF = 'app.urls'
INSTALLED_APPS = [
...,
'rest_framework',
'restdoctor',
]
MIDDLEWARE = [
...,
'restdoctor.django.middleware.api_selector.ApiSelectorMiddleware',
]
API_FALLBACK_VERSION = 'fallback'
API_FALLBACK_FOR_APPLICATION_JSON_ONLY = False
API_DEFAULT_VERSION = 'v1'
API_DEFAULT_FORMAT = 'full'
API_PREFIXES = ('/api',)
API_FORMATS = ('full', 'compact')
API_RESOURCE_DISCRIMINATIVE_PARAM = 'view_type'
API_RESOURCE_DEFAULT = 'common'
API_RESOURCE_SET_PARAM = False
API_RESOURCE_SET_PARAM_FOR_DEFAULT = False
API_V1_URLCONF = 'api.v1_urls'
API_VERSIONS = {
'fallback': ROOT_URLCONF,
'v1': API_V1_URLCONF,
}
Использование в проекте
Максимально наследуемся от restdoctor там, где есть выбор между rest_framework
и restdoctor.rest_framework
.
from restdoctor.rest_framework.serializers import ModelSerializer
from restdoctor.rest_framework.views import GenericAPIView, RetrieveAPIView, ListAPIView
from restdoctor.rest_framework.viewsets import ModelViewSet, ReadOnlyModelViewSet
Версионирование
RestDoctor маршрутизирует вызовы по заголовку Accept
на изолированный UrlConf
.
- Во-первых, это означает, что без корректного заголовка
Accept
ручки API могут быть недоступны и отдавать 404. - А во-вторых, в приложении может быть несколько различных версий API, которые не будут "видеть" друг друга.
Общий формат заголовка следующий:
application/vnd.{vendor}.{version}[-{resource}][.{format}][+json]
Где vendor задается на уровне приложения параметром API_VENDOR_STRING
, список версий и сопоставление их UrlConf'ам
определяется параметром API_VERSIONS
.
Саму маршрутизацию для входящего запроса проводит middleware ApiSelectorMiddleware
, которую надо включить в
настройках.
ROOT_URLCONF = 'app.urls'
MIDDLEWARE = [
...,
'restdoctor.django.middleware.api_selector.ApiSelectorMiddleware',
]
API_V1_URLCONF = 'api.v1.urls'
API_VENDOR_STRING = 'RestDoctor'
API_FALLBACK_VERSION = 'fallback'
API_DEFAULT_VERSION = 'v1'
API_VERSIONS = {
API_FALLBACK_VERSION: ROOT_URLCONF,
API_DEFAULT_VERSION: API_V1_URLCONF,
}
Маршрутизация по API_VERSIONS
срабатывает, если Accept начинается с application/vnd.{vendor}
,
если не указана версия, то берется API_DEFAULT_VERSION
. Если Accept не содержит корректной vendor-строки, то
выбирается API_FALLBACK_VERSION
.
Версия может быть указана в формате {version}-{resource}
, тогда ResourceViewSet
будет использовать эту информацию
для выбора ViewSet
.
Кроме того, может быть дополнительно указан {format}
для выбора формата ответа, по факту выбор сериализатора в
SerializerClassMapApiView
.
В случае успешного определения версии и параметров API из заголовка Accept, middleware выбирает для дальнейшей обработки
запроса конкретный UrlConf и добавляет к объекту request
атрибут api_params
.
Формат ответа API
Нашим API Guide задан формат ответа, за который отвечает RestDoctorRenderer
(restdoctor.rest_framework.renderers.RestDoctorRenderer
). Включается он только для запросов, содержащих атрибут
api_params
, и работает этот механизм через content_negotiation_class
заданный в базовом для View и ViewSet
миксине NegotiatedMixin (restdoctor.rest_framework.mixins.NegotiatedMixin
).
SerializerClassMapApiView
DRF позволяет достаточно компактно определять ModelSeraizlier
+ ModelViewSet
, однако оставляет достаточно много
свободы в одних местах, не предоставляя ее в других.
Например, можно переопределить serializer_class
в классе ViewSet'а, либо определять его динамически через
ViewSet.get_serializer_class
, однако нельзя переопределять сериализаторы отдельно для запроса, отдельно для ответа.
Т.е. нельзя задать отдельный сериализатор для update
, используя сериализатор для retrieve
для возврата измененной
сущности.
SerializerClassMapApiView
дает возможность декларативно задавать сериализаторы для различных action, отдельно для
request и response.
Поддержка на уровне базовых миксинов для ViewSet'ов позволяет прозрачно заменить, например,
ReadOnlyModelViewSet
в импортах с rest_framework.viewsets
на restdoctor.rest_framework.viewsets
.
serializer_class_map
SerializerClassMapApiView
позволяет задавать сериализаторы для разных action'ов и форматов ответа отдельно для
request и response фазы обработки запроса.
from restdoctor.rest_framework.viewsets import ModelViewSet
from app.api.serializers import (
MyDefaultSerializer, MyCompactSerializer, MyAntoherSerializer,
MyCreateSerializer, MyUpdateSerializer,
)
class MyApiView(SerializerClassMapApiView):
"""Пример работы с serializer_class_map."""
serializer_class_map = {
'default': MyDefaultSerializer,
'default.compact': MyCompactSerializer,
'create': {
'request': MyCreateSerializer,
},
'update': {
'request': MyUpdateSerializer,
},
'list': {
'response.another_format': MyAnotherSerializer,
}
}
В этом примере мы задаем MyDefaultSerializer
как базовый для ViewSet. Но для create
и update
action
переопределяем сериализаторы для обработки request'а.
Кроме того, мы определили сериализатор для compact
формата и отдельно для list
action для another_format
.
permission_classes_map
По аналогии с serializer_class_map
для декларативного задания разных наборов permission_classes
на разных action'ах
можно определить permission_classes_map
:
from restdoctor.rest_framework.viewsets import ModelViewSet
from app.api.permissions import PermissionA, PermissionB
class MyViewSet(ModelViewSet):
permission_classes_map = {
'default': [PermissionA],
'retrieve': [PermissionB],
}
Замечание про action
В DRF action появляется во время регистрации ViewSet
с помощью Router
. При этом для разделения list/detail ресурсов
используются разные наборы action_maps
:
list_action_map = {'get': 'list', 'post': 'create'}
detail_action_map = {'get': 'retrieve', 'put': 'update'}
Django-механизмы роутинга создают функцию-обработчик, которая инстанцирует View/ViewSet с нужными параметрами.
При этом один и тот же класс ViewSet
будет присутствовать в UrlConf в двух экземплярах с разными action_map
.
Во время обработки запроса по HTTP методу будет определен action и вызван соответствующий метод экземпляра ViewSet
.
И во время обработки запроса у ViewSet
всегда задан self.action
.
Однако это не так для View
, поэтому в SerializerClassMapApiView
добавлен атрибут action
, на который завязывается
поиск сериализатора в serializer_class_map
.
Миксины и ModelViewSet
Миксины задают базовые операции ModelViewSet
для 'list'
, 'retrieve'
, 'create'
, 'update'
, 'destroy'
action'ов.
От DRF-версий они отличаются в основном тем, что используют SerializerClassMapApiView.get_request_serializer
и
SerializerClassMapApiView.get_response_serializer
вместо View.get_serializer
.
ListModelMixin
Определяет обработчик для list
action. Определяет метод get_collection
:
class ListModelMixin(BaseListModelMixin):
def list(self, request: Request, *args: typing.Any, **kwargs: typing.Any) -> Response:
queryset = self.get_collection()
...
def get_collection(self, request_serializer: BaseSerializer) -> typing.Union[typing.List, QuerySet]:
return self.filter_queryset(self.get_queryset())
Т.е. можно использовать ListModelMixin
для работы с любыми коллекциями, а не только моделями, надо только
переопределить ViewSet.get_collection
. При этом, если задан сериализатор для list
, то он будет использован
для query-параметров, что позволит получить эти параметры и использовать дополнительно к filterset'у.
ListModelViewSet
Задан только обработчик для list
action.
ReadOnlyModelViewSet
Заданы обработчики для list
и retrieve
action'ов.
CreateUpdateReadModelViewSet
Заданы обработчики для list
, retrieve
, create
, update
action'ов.
ModelViewSet
Полный набор action'ов: list
, retrieve
, create
, update
, destroy
.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for restdoctor-0.0.33-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f415c2f848e7f77fa4891e04595faf89a00ed46a63a6300e469a023f1e8defac |
|
MD5 | b09df06638c7b67f5ffb569f91051d81 |
|
BLAKE2b-256 | 02646c4c65f50a66bc57fd6aced80c45bc617429cf3ff7faa111a4be7722c00d |