Форматные суффиксы

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

‒ Рой Филдинг, REST discuss mailing list

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

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

шаблоны_суффикса

Подпись : 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...

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

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

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

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

url patterns = [
    …
]

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

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

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

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

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

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

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

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

&ldquo;Вот почему я всегда предпочитаю расширения. Ни тот, ни другой выбор не имеют ничего общего с REST.&rdquo; ‒ Рой Филдинг, REST discuss mailing list.

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

Вернуться на верх