> For the complete documentation index, see [llms.txt](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ilyachch.gitbook.io/django-rest-framework-russian-documentation/overview/navigaciya-po-api/format-suffixes.md).

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

> В разделе 6.2.1 не говорится, что согласование содержания должно использоваться постоянно.
>
> * Рой Филдинг, [список рассылки REST discuss](http://tech.groups.yahoo.com/group/rest-discuss/message/5857)

Общим шаблоном для веб-интерфейсов является использование расширений имен файлов в 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**: Необязательно. Список или кортеж допустимых суффиксов формата. Если не указан, будет использоваться шаблон суффикса формата.

Пример:

```python
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'` в соответствующие представления. Например:

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

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

```python
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` применяется как конечная, или крайняя функция. Например:

```python
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".
>
> * Рой Филдинг, [Список рассылки REST discuss](https://groups.yahoo.com/neo/groups/rest-discuss/conversations/topics/14844)

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