GitHub 検索 Django REST framework
urlpatterns.py

フォーマットサフィックス

セクション6.2.1では、コンテンツネゴシエーションを常に使用する必要があるとは述べていません。

— Roy Fielding、RESTディスカスメーリングリスト

Web APIの一般的なパターンは、URLにファイル名拡張子を使用して、特定のメディアタイプのエンドポイントを提供することです。たとえば、「http://example.com/api/users.json」はJSON表現を提供します。

APIのURLconfの個々のエントリにフォーマットサフィックスパターンを追加すると、エラーが発生しやすく、DRYではなくなるため、REST frameworkはこれらのパターンを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...

使用されるkwargの名前は、FORMAT_SUFFIX_KWARG設定を使用して変更できます。

また、format_suffix_patternsはincludeURLパターンへの下降をサポートしていないことに注意してください。

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ヘッダーとフォーマットサフィックス

Webコミュニティの一部には、ファイル名拡張子はRESTfulなパターンではなく、代わりに常にHTTP Acceptヘッダーを使用する必要があるという見解があるようです。

これは実際には誤解です。たとえば、クエリパラメータのメディアタイプインジケーターとファイル拡張子のメディアタイプインジケーターの相対的なメリットについて議論しているRoy Fieldingからの次の引用を見てください。

「だから私はいつも拡張子を好みます。どちらの選択もRESTとは関係ありません。」— Roy Fielding、RESTディスカスメーリングリスト

引用はAcceptヘッダーについては言及していませんが、フォーマットサフィックスが受け入れられるパターンと見なされるべきであることを明確にしています。