Format 后缀

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

在 URLconf 中为你的 API 添加 format-suffix 模式是容易出错和非 DRY 的,因此 REST framework 提供了将这些模式添加到 URLconf 的快捷方式。

format_suffix_patterns

签名: format_suffix_patterns(urlpatterns, suffix_required=False, allowed=None)

返回一个 URL pattern 列表,其中包含附加到每个 URL pattern 的格式后缀模式。

参数:

  • urlpatterns: 必需。一个 URL pattern 列表。
  • suffix_required: 可选。一个 boolean 值,指定 URL 中的后缀是否可选或强制。默认为 False,这意味着后缀默认是可选的。
  • allowed: 可选。有效格式后缀的列表或元组。如果没有提供,将使用通配符格式后缀模式。

例如:

from rest_framework.urlpatterns import format_suffix_patterns
from blog import views

urlpatterns = [
    url(r'^/$', views.apt_root),
    url(r'^comments/$', views.comment_list),
    url(r'^comments/(?P<pk>[0-9]+)/$', 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 setting 进行修改。

另请注意,format_suffix_patterns 不支持降序包含 URL patterns。

i18n_patterns 一起使用

如果使用 Django 提供的 i18n_patterns 函数以及 format_suffix_patterns,则应确保将 i18n_patterns 函数用作最终或最外层函数。例如:

url patterns = [
    …
]

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

查询参数 format

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

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

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

返回 URL

通常,从 Web API(例如 http://example.com/foobar)返回绝对 URI 可能是更好的做法,而不是返回相对 URI,例如 /foobar

这样做的好处有:

  • 它更明确。
  • 它为你的 API 客户端留下更少的工作。
  • 当字符串在诸如 JSON 这样的表示中没有本地 URI 类型时,它的含义是没有歧义的。
  • 它使得使用超链接标记 HTML 表示等事情变得很容易。

REST framework 提供了两个实用函数,可以更简单地从 Web API 返回绝对 URI。

使用它们不是必须的,但是如果你这样做,自描述 API 将能够自动为你输出超链接,这使得浏览 API 变得更容易。

reverse

签名: reverse(viewname, *args, **kwargs)

具有与 django.urls.reverse 相同的行为,除了它返回一个完全限定的 URL,使用 request 来确定主机和端口。

你应该将 request 作为关键字参数包含在该函数中,例如:

from rest_framework.reverse import reverse
from rest_framework.views import APIView
from django.utils.timezone import now

class APIRootView(APIView):
    def get(self, request):
        year = now().year
        data = {
            ...
            'year-summary-url': reverse('year-summary', args=[year], request=request)
        }
        return Response(data)

reverse_lazy

签名: reverse_lazy(viewname, *args, **kwargs)

具有与 django.urls.reverse_lazy 相同的行为,除了它返回一个完全限定的 URL,使用 request 来确定主机和端口。

reverse 函数一样,你应该将 request 作为关键字参数包含在函数中,例如:

api_root = reverse_lazy('api-root', request=request)
本文作者:博主:
文章标题:Django DRF(二十)-Format 后缀和返回 URL
本文地址:https://wouldmissyou.com/archives/70/     
版权说明:若无注明,本文皆为“多点部落”原创,转载请保留文章出处。
最后修改:2021 年 02 月 04 日 05 : 08 PM
如果觉得我的文章对你有用,请随意赞赏