GitHub 搜索 Django REST 框架
urlpatterns.py

格式后缀

第 6.2.1 节没有说明内容协商应该始终使用。

— Roy Fielding，REST 讨论邮件列表

Web API 的常见模式是在 URL 上使用文件名扩展名，以提供给定媒体类型的端点。例如，“http://example.com/api/users.json”用于提供 JSON 表示。

在 API 的 URLConf 中为每个单独条目添加格式后缀模式容易出错且不 DRY，因此 REST 框架提供了一个快捷方式来将这些模式添加到 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 不支持降级到 include URL 模式。

与 i18n_patterns 一起使用

如果使用 Django 提供的 i18n_patterns 函数以及 format_suffix_patterns，则应确保将 i18n_patterns 函数应用为最后一个或最外层的函数。例如

urlpatterns = [
    …
]

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

查询参数格式

格式后缀的替代方法是将请求的格式包含在查询参数中。REST 框架默认提供此选项，并在可浏览的 API 中使用它来在不同的可用表示之间切换。

要使用其短格式选择表示，请使用 format 查询参数。例如：http://example.com/organizations/?format=csv。

可以使用 URL_FORMAT_OVERRIDE 设置修改此查询参数的名称。将值设置为 None 以禁用此行为。

Accept 标头与格式后缀

网络社区中的一些人似乎认为文件名扩展名不是 RESTful 模式，而应始终使用 HTTP Accept 标头。

这实际上是一个误解。例如，引用 Roy Fielding 对查询参数媒体类型指示符与文件扩展名媒体类型指示符的相对优点的讨论

“这就是我始终喜欢扩展名的原因。两种选择都与 REST 无关。”——Roy Fielding，REST 讨论邮件列表

引文未提及 Accept 标头，但它明确说明格式后缀应被视为可接受的模式。