Skip to content

Latest commit

 

History

History
98 lines (64 loc) · 6.25 KB

format-suffixes.md

File metadata and controls

98 lines (64 loc) · 6.25 KB

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

В разделе 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 предоставляет этот параметр по умолчанию, и он используется в просматриваемом API для переключения между различными доступными представлениями.

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

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

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

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

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

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

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