Django REST Framework
  • Overview
    • Django REST framework
    • Быстрый старт
      • Сериализация
      • Запросы-ответы
      • Представления-классы
      • Аутентификация/права доступа
      • Отношения и связи
      • Наборы представлений и роутеры
    • Навигация по API:
      • Запросы
      • Ответы
      • Представления
      • Общие представления
      • Viewsets
      • Маршрутизаторы
      • Парсеры
      • Рендереры
      • Сериализаторы
      • Поля сериализатора
      • Отношения сериализаторов
      • Валидаторы
      • Аутентификация
      • Разрешения
      • Кэширование
      • Дросселирование
      • Фильтрация
      • Пагинация
      • Версионирование
      • Согласование контента
      • Метаданные
      • Schemas
      • Cуффиксы формата
      • Возвращение URL-адресов
      • Исключения
      • Коды состояния
      • Тестирование
      • Настройки
  • Статьи
    • Статьи
      • AJAX, CSRF & CORS
      • The Browsable API
      • Улучшения в браузере
      • Документирование вашего API
      • HTML и формы
      • Интернационализация
      • REST, гипермедиа и HATEOAS
      • Вложенные сериализаторы с возможностью записи
Powered by GitBook
On this page
  • format_suffix_patterns
  • Использование с i18n_patterns.
  • Форматы параметров запроса
  • Принимать заголовки против суффиксов формата

Was this helpful?

  1. Overview
  2. Навигация по API:

Cуффиксы формата

PreviousSchemasNextВозвращение URL-адресов

Last updated 1 year ago

Was this helpful?

В разделе 6.2.1 не говорится, что согласование содержания должно использоваться постоянно.

  • Рой Филдинг,

Общим шаблоном для веб-интерфейсов является использование расширений имен файлов в URL-адресах для предоставления конечной точки для данного типа носителя. Например, 'http://example.com/api/users.json' для предоставления представления JSON.

Добавление шаблонов суффиксов формата к каждой отдельной записи в URLconf для вашего API чревато ошибками и не соответствует стандарту DRY, поэтому DRF предоставляет быстрый способ добавления этих шаблонов в URLConf.

format_suffix_patterns

Сигнатура: format_suffix_patterns(urlpatterns, suffix_required=False, allowed=None)

Возвращает список шаблонов URL, который включает шаблоны суффиксов формата, добавленные к каждому из предоставленных шаблонов URL.

Аргументы:

  • urlpatterns: Обязательно. Список шаблонов URL.

  • suffix_required: Необязательно. Булево значение, указывающее, должны ли суффиксы в URL быть необязательными или обязательными. По умолчанию False, что означает, что суффиксы по умолчанию необязательны.

  • allowed: Необязательно. Список или кортеж допустимых суффиксов формата. Если не указан, будет использоваться шаблон суффикса формата.

Пример:

from rest_framework.urlpatterns import format_suffix_patterns
from blog import views

urlpatterns = [
    path('', views.apt_root),
    path('comments/', views.comment_list),
    path('comments/<int:pk>/', views.comment_detail)
]

urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html'])

При использовании format_suffix_patterns, вы должны убедиться, что добавили именованный аргумент 'format' в соответствующие представления. Например:

@api_view(['GET', 'POST'])
def comment_list(request, format=None):
    # do stuff...

Или с помощью представлений, основанных на классах:

class CommentList(APIView):
    def get(self, request, format=None):
        # do stuff...

    def post(self, request, format=None):
        # do stuff...

Имя используемого именнованного аргумента можно изменить с помощью параметра FORMAT_SUFFIX_KWARG.

Также обратите внимание, что format_suffix_patterns не поддерживает применение к шаблонам URL include.

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

При использовании функции i18n_patterns, предоставляемой Django, а также format_suffix_patterns вы должны убедиться, что функция i18n_patterns применяется как конечная, или крайняя функция. Например:

urlpatterns = [
    …
]

urlpatterns = i18n_patterns(
    format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
)

Форматы параметров запроса

Альтернативой суффиксам формата является включение запрашиваемого формата в параметр запроса. DRF предоставляет этот параметр по умолчанию, и он используется в Web-интерфейсе API для переключения между различными доступными представлениями.

Чтобы выбрать представление по его краткому формату, используйте параметр запроса format. Например: http://example.com/organizations/?format=csv.

Имя этого параметра запроса можно изменить с помощью параметра URL_FORMAT_OVERRIDE. Установите значение None, чтобы отключить это поведение.


Принимать заголовки против суффиксов формата

Похоже, некоторые представители веб-сообщества считают, что расширения имен файлов не являются шаблоном RESTful, и что вместо них всегда следует использовать заголовки HTTP Accept.

На самом деле это заблуждение. Например, возьмем следующую цитату Роя Филдинга, обсуждающего относительные достоинства индикаторов медиатипа параметров запроса по сравнению с индикаторами медиатипа расширений файлов:

Вот почему я всегда предпочитаю расширения. Ни тот, ни другой выбор не имеют никакого отношения к REST".

В цитате не упоминаются заголовки Accept, но она ясно дает понять, что суффиксы формата следует считать приемлемым шаблоном.

Рой Филдинг,

список рассылки REST discuss
Список рассылки REST discuss