Форматные суффиксы¶
В разделе 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
.
На самом деле это заблуждение. Например, возьмем следующую цитату Роя Филдинга, обсуждающего относительные достоинства индикаторов медиатипа параметров запроса по сравнению с индикаторами медиатипа расширений файлов:
“Вот почему я всегда предпочитаю расширения. Ни тот, ни другой выбор не имеют ничего общего с REST.” ‒ Рой Филдинг, REST discuss mailing list.
В цитате не упоминаются заголовки Accept, но она ясно дает понять, что суффиксы формата следует считать приемлемым шаблоном.