メタデータ
OPTIONSメソッドにより、クライアントはリソースアクションを暗示したりリソースの取得を開始したりすることなく、リソースに関連付けられたオプションや要件、またはサーバーの機能を確認できます。
REST frameworkには、APIがOPTIONSリクエストにどのように応答するかを決定するための設定可能なメカニズムが含まれています。これにより、APIスキーマやその他のリソース情報を返すことができます。
HTTP OPTIONSリクエストに対してどのような形式のレスポンスを返すかについては、現在広く採用されている規則はありません。そのため、いくつかの有用な情報を返すアドホックな形式を提供しています。
以下は、デフォルトで返される情報を示すレスポンス例です。
HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
{
"name": "To Do List",
"description": "List existing 'To Do' items, or create a new item.",
"renders": [
"application/json",
"text/html"
],
"parses": [
"application/json",
"application/x-www-form-urlencoded",
"multipart/form-data"
],
"actions": {
"POST": {
"note": {
"type": "string",
"required": false,
"read_only": false,
"label": "title",
"max_length": 100
}
}
}
}
メタデータスキームの設定
'DEFAULT_METADATA_CLASS'設定キーを使用して、メタデータクラスをグローバルに設定できます。
REST_FRAMEWORK = {
'DEFAULT_METADATA_CLASS': 'rest_framework.metadata.SimpleMetadata'
}
または、ビューごとにメタデータクラスを個別に設定できます。
class APIRoot(APIView):
metadata_class = APIRootMetadata
def get(self, request, format=None):
return Response({
...
})
REST frameworkパッケージには、SimpleMetadataという名前のメタデータクラス実装が1つだけ含まれています。別のスタイルを使用する場合は、カスタムメタデータクラスを実装する必要があります。
スキーマエンドポイントの作成
通常のGETリクエストでアクセスされるスキーマエンドポイントを作成するための特定の要件がある場合は、メタデータAPIを再利用することを検討してください。
たとえば、ビューセットで次の追加ルートを使用して、リンク可能なスキーマエンドポイントを提供できます。
@action(methods=['GET'], detail=False)
def api_schema(self, request):
meta = self.metadata_class()
data = meta.determine_metadata(request, self)
return Response(data)
このアプローチを選択する理由はいくつかあります。たとえば、OPTIONSレスポンスはキャッシュできません。
カスタムメタデータクラス
カスタムメタデータクラスを提供する場合は、BaseMetadataをオーバーライドし、determine_metadata(self, request, view)メソッドを実装する必要があります。
JSONスキーマなどの形式を使用してスキーマ情報を返したり、管理ユーザーにデバッグ情報を返したりするなど、役立つ操作を実行できます。
例
次のクラスを使用して、OPTIONSリクエストに返される情報を制限できます。
class MinimalMetadata(BaseMetadata):
"""
Don't include field and other information for `OPTIONS` requests.
Just return the name and description.
"""
def determine_metadata(self, request, view):
return {
'name': view.get_view_name(),
'description': view.get_view_description()
}
次に、このカスタムクラスを使用するように設定を設定します。
REST_FRAMEWORK = {
'DEFAULT_METADATA_CLASS': 'myproject.apps.core.MinimalMetadata'
}
サードパーティパッケージ
以下のサードパーティパッケージは、追加のメタデータ実装を提供します。
DRF-schema-adapter
drf-schema-adapter は、フロントエンドのフレームワークやライブラリにスキーマ情報を提供しやすくするツールセットです。メタデータミキシンと2つのメタデータクラス、およびjson-schemaとさまざまなライブラリが読み取ることができるスキーマ情報を生成するのに適切な複数のアダプターを提供します。
特定のフロントエンドで動作するように独自のアダプターを作成することもできます。そうする場合、スキーマ情報をjsonファイルにエクスポートできるエクスポーターも提供されます。