Использование¶

Вот пример простого URL conf, в котором используется SimpleRouter.

from rest_framework import routers

router = routers.SimpleRouter()
router.register(r'users', UserViewSet)
router.register(r'accounts', AccountViewSet)
urlpatterns = router.urls

Для метода register() есть два обязательных аргумента:

• prefix - Префикс URL, который будет использоваться для данного набора маршрутов.

• viewset - Класс набора представлений.

По желанию вы можете указать дополнительный аргумент:

• basename - Основа, которую следует использовать для создаваемых имен URL. Если базовое имя не задано, оно будет автоматически генерироваться на основе атрибута queryset набора представлений, если таковой имеется. Обратите внимание, что если набор представлений не включает атрибут queryset, то вы должны установить basename при регистрации набора представлений.

В приведенном выше примере будут сгенерированы следующие шаблоны URL:

• Шаблон URL: ^users/$ Имя: 'user-list'

• Шаблон URL: ^users/{pk}/$ Имя: 'user-detail'

• Шаблон URL: ^accounts/$ Имя: 'account-list'

• Шаблон URL: ^accounts/{pk}/$ Имя: 'account-detail'

Примечание : Аргумент basename используется для указания начальной части шаблона имени представления. В приведенном примере это часть user или account.

Обычно вам не нужно указывать аргумент basename, но если у вас есть набор представлений, в котором вы определили пользовательский метод get_queryset, то набор представлений может не иметь установленного атрибута .queryset. Если вы попытаетесь зарегистрировать этот набор представлений, вы увидите ошибку, подобную этой:

'basename' argument not specified, and could not automatically determine the name from the viewset, as it does not have a '.queryset' attribute.

Это означает, что вам нужно будет явно задать аргумент basename при регистрации набора представлений, поскольку он не может быть автоматически определен из имени модели.

router = routers.SimpleRouter()
router.register(r'users', UserViewSet)
router.register(r'accounts', AccountViewSet)

urlpatterns = [
    path('forgot-password/', ForgotPasswordFormView.as_view()),
]

urlpatterns += router.urls

urlpatterns = [
    path('forgot-password', ForgotPasswordFormView.as_view()),
    path('', include(router.urls)),
]

urlpatterns = [
    path('forgot-password/', ForgotPasswordFormView.as_view()),
    path('api/', include((router.urls, 'app_name'))),
]

urlpatterns = [
    path('forgot-password/', ForgotPasswordFormView.as_view()),
    path('api/', include((router.urls, 'app_name'), namespace='instance_name')),
]

from myapp.permissions import IsAdminOrIsSelf
from rest_framework.decorators import action

class UserViewSet(ModelViewSet):
    ...

    @action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf])
    def set_password(self, request, pk=None):
        ...

from myapp.permissions import IsAdminOrIsSelf
from rest_framework.decorators import action

class UserViewSet(ModelViewSet):
    ...

    @action(methods=['post'], detail=True, permission_classes=[IsAdminOrIsSelf],
            url_path='change-password', url_name='change_password')
    def set_password(self, request, pk=None):
        ...

SimpleRouter¶

Этот маршрутизатор включает маршруты для стандартного набора действий list , create , retrieve , update , partial_update и destroy. Набор представлений может также отметить дополнительные методы для маршрутизации, используя декоратор @action.

По умолчанию URL, созданные с помощью SimpleRouter, дополняются косой чертой. Это поведение можно изменить, установив аргумент trailing_slash в False при инстанцировании маршрутизатора. Например:

router = SimpleRouter(trailing_slash=False)

В Django косые черты являются традиционными, но не используются по умолчанию в некоторых других фреймворках, таких как Rails. Какой стиль использовать - это в основном вопрос предпочтений, хотя некоторые javascript-фреймворки могут ожидать определенного стиля маршрутизации.

Маршрутизатор будет соответствовать значениям поиска, содержащим любые символы, кроме косой черты и точки. Для более строгого (или мягкого) шаблона поиска установите атрибут lookup_value_regex в наборе представлений. Например, можно ограничить поиск действительными UUID:

class MyModelViewSet(mixins.RetrieveModelMixin, viewsets.GenericViewSet):
    lookup_field = 'my_model_id'
    lookup_value_regex = '[0-9a-f]{32}'

DefaultRouter¶

Этот маршрутизатор похож на SimpleRouter, как описано выше, но дополнительно включает корневое представление API по умолчанию, которое возвращает ответ, содержащий гиперссылки на все представления списка. Он также генерирует маршруты для необязательных суффиксов формата стиля .json.

Как и в случае с SimpleRouter, косые черты в маршрутах URL можно убрать, установив аргумент trailing_slash в значение False при инстанцировании маршрутизатора.

router = DefaultRouter(trailing_slash=False)

Настройка динамических маршрутов¶

Вы также можете настроить маршрутизацию декоратора @action. Включите именованный кортеж DynamicRoute в список .routes, установив аргумент detail соответствующим образом для маршрутов на основе списка и на основе деталей. В дополнение к detail , аргументами для DynamicRoute являются:

url : Строка, представляющая URL, который должен быть маршрутизирован. Может включать те же строки формата, что и Route , и дополнительно принимает строку формата {url_path}.

name : Имя URL, используемое в вызовах reverse. Может включать следующие строки формата:

• {basename} - Основа, которую следует использовать для создаваемых имен URL.

• {url_name} - url_name, предоставляемый @action.

initkwargs : Словарь дополнительных аргументов, которые должны быть переданы при инстанцировании представления.

Пример¶

Следующий пример маршрутизирует только действия list и retrieve и не использует соглашение о косой черте.

from rest_framework.routers import Route, DynamicRoute, SimpleRouter

class CustomReadOnlyRouter(SimpleRouter):
    """
    A router for read-only APIs, which doesn't use trailing slashes.
    """
    routes = [
        Route(
            url=r'^{prefix}$',
            mapping={'get': 'list'},
            name='{basename}-list',
            detail=False,
            initkwargs={'suffix': 'List'}
        ),
        Route(
            url=r'^{prefix}/{lookup}$',
            mapping={'get': 'retrieve'},
            name='{basename}-detail',
            detail=True,
            initkwargs={'suffix': 'Detail'}
        ),
        DynamicRoute(
            url=r'^{prefix}/{lookup}/{url_path}$',
            name='{basename}-{url_name}',
            detail=True,
            initkwargs={}
        )
    ]

Давайте посмотрим, какие маршруты будет генерировать наш CustomReadOnlyRouter для простого набора представлений.

views.py :

class UserViewSet(viewsets.ReadOnlyModelViewSet):
    """
    A viewset that provides the standard actions
    """
    queryset = User.objects.all()
    serializer_class = UserSerializer
    lookup_field = 'username'

    @action(detail=True)
    def group_names(self, request, pk=None):
        """
        Returns a list of all the group names that the given
        user belongs to.
        """
        user = self.get_object()
        groups = user.groups.all()
        return Response([group.name for group in groups])

urls.py :

router = CustomReadOnlyRouter()
router.register('users', UserViewSet)
urlpatterns = router.urls

Будут созданы следующие отображения…

Для другого примера установки атрибута .routes смотрите исходный код класса SimpleRouter.

Усовершенствованные пользовательские маршрутизаторы¶

Если вы хотите обеспечить полностью пользовательское поведение, вы можете переопределить BaseRouter и переопределить метод get_urls(self). Метод должен проверять зарегистрированные наборы представлений и возвращать список шаблонов URL. Зарегистрированные кортежи prefix, viewset и basename могут быть проверены путем обращения к атрибуту self.registry.

Вы также можете переопределить метод get_default_basename(self, viewset), или всегда явно задавать аргумент basename при регистрации ваших наборов представлений в маршрутизаторе.

Вложенные маршрутизаторы DRF¶

drf-nested-routers package предоставляет маршрутизаторы и поля отношений для работы с вложенными ресурсами.

ModelRouter (wq.db.rest)¶

wq.db package предоставляет расширенный ModelRouter класс (и экземпляр синглтона), который расширяет DefaultRouter с register_model() API. Как и в admin.site.register в Django, единственным необходимым аргументом для rest.router.register_model является класс модели. Разумные значения по умолчанию для префикса url, сериализатора и набора представлений будут выведены из модели и глобальной конфигурации.

from wq.db import rest
from myapp.models import MyModel

rest.router.register_model(MyModel)

DRF-расширения¶

** ``DRF-extensions:doc:` package <https://chibisov.github.io/drf-extensions/docs/>` обеспечивает routers для создания nested viewsets с customizable endpoint names.