Django REST framework API 指南（22）：Format 字尾

wcode發表於2018-03-22
DjangoRESTFrameworkAPIORM

官方原文連結
本系列文章 github 地址
轉載請註明出處

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 字尾的替代方法是將請求的 format 包含在查詢引數中。REST framework 預設提供此選項，並且它在可瀏覽的 API 中用於在不同的可用表示之間切換。

要使用其短格式表示，請使用 format 查詢引數。例如： http://example.com/organizations/?format=csv。

此查詢引數的名稱可以使用 URL_FORMAT_OVERRIDE 設定進行修改。將該值設定為 None 以禁用此行為。

相關文章