[DRF] 공식 문서 - Metadata 정리

 1. Metadata

   - REST 프레임워크는 OPTIONS 요청에 대해 API가 어떻게 응답해야 하는지 결정하는 구성 가능한 메커니즘을 포함하고 있습니다. 이를 통해 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
            }
        }
    }
}

 

   1) 메타데이터 체계 설정(Setting the metadata scheme)

      - '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 프레임워크 패키지에는 SimpleMetadata라는 하나의 메타데이터 클래스 구현체만 포함되어 있다. 다른 스타일을 사용하려면 사용자 정의 메타데이터 클래스를 구현해야 한다.

 

   2) 스키마 엔드포인트 생성(Creating schema endpoints)

      - 일반적인 GET 요청으로 액세스되는 스키마 엔드포인트를 생성하는 특정 요구 사항이 있다면, 메타데이터 API를 재사용하는 것을 고려할 수 있다.

      - 예를 들어, 다음과 같은 추가적인 route를 뷰셋에 사용하여 링크 가능한 스키마 엔드포인트를 제공할 수 있다.

@action(methods=['GET'], detail=False)
def api_schema(self, request):
    meta = self.metadata_class()
    data = meta.determine_metadata(request, self)
    return Response(data)

 

      - 이러한 접근 방식을 선택하는 이유는 여러 가지가 있을 수 있다. 그 중 하나는 OPTIONS 응답이 캐시할 수 없다는 점이다.

         - are not cacheable : https://www.mnot.net/blog/2012/10/29/NO_OPTIONS

 

 2. 사용자 정의 메타데이터 클래스(Custom metadata classes)

   - 사용자 정의 메타데이터 클래스를 제공하려면 BaseMetadata를 재정의하고 determine_metadata(self, request, view) 메서드를 구현해야 한다.

   - 반환할 수 있는 유용한 정보로는 JSON 스키마와 같은 형식으로 스키마 정보를 반환하거나, 디버그 정보를 관리자 사용자에게 반환하는 등의 작업이 있을 수 있다.

      - JSON schema : https://json-schema.org/

 

   1) Example

      - 다음 클래스는 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'
}

 

 3. Third party packages

   1) DRF-schema-adapter

      - drf-schema-adapter는 프런트엔드 프레임워크와 라이브러리에 스키마 정보를 제공하기 쉽게하는 도구 세트이다. 메타데이터 mixin과 2개의 메타데이터 클래스, 여러 개의 어댑터를 제공하여 json-schema 및 다양한 라이브러리에서 읽을 수 있는 스키마 정보를 생성하는 데 적합하다.

      - 또한 특정 프런트엔드와 함께 작업하기 위해 직접 어댑터를 작성할 수도 있다. 이 경우 해당 스키마 정보를 json 파일로 내보내는 내보내기 도구도 제공된다.

 

- drf-schema-adapter : https://github.com/drf-forms/drf-schema-adapter

- json-schema : https://json-schema.org/

 

      - 예시

from rest_framework.views import APIView
from rest_framework.response import Response
from drf_schema_adapter.metadata import SchemaMetadataMixin
from drf_schema_adapter.metadata import JsonSchemaMetadataClass

class MyAPIView(SchemaMetadataMixin, APIView):
    """
    MyAPIView는 스키마 메타데이터를 제공하는 APIView입니다.
    """

    metadata_class = JsonSchemaMetadataClass
    """
    metadata_class는 JsonSchemaMetadataClass를 사용하여 JSON 스키마 메타데이터를 생성합니다.
    """

    def get(self, request):
        """
        GET 요청을 처리하는 메소드입니다.
        """

        data = {
            'message': 'Hello, world!',
            'count': 10,
            'results': ['item1', 'item2', 'item3']
        }
        return Response(data)

    def post(self, request):
        """
        POST 요청을 처리하는 메소드입니다.
        """

        # Request body 스키마 정보를 생성합니다.
        request_schema = {
            'type': 'object',
            'properties': {
                'name': {'type': 'string'},
                'age': {'type': 'integer'}
            },
            'required': ['name']
        }

        # Response body 스키마 정보를 생성합니다.
        response_schema = {
            'type': 'object',
            'properties': {
                'message': {'type': 'string'}
            }
        }

        # 스키마 정보를 메타데이터에 등록합니다.
        self.set_request_body_schema(request, request_schema)
        self.set_response_body_schema(response_schema)

        # 요청 처리 로직을 구현합니다.
        name = request.data.get('name')
        age = request.data.get('age')
        message = f"Hello, {name}! You are {age} years old."
        data = {
            'message': message
        }
        return Response(data)

 

      - 위의 코드는 DRF-schema-adapter를 사용하여 스키마 정보를 제공하는 예시이다. MyAPIView 클래스는 APIView를 상속하고, SchemaMetadataMixin을 사용하여 스키마 메타데이터를 제공한다. metadata_class 속성을 설정하여 JSON 스키마 메타데이터를 생성하는 JsonSchemaMetadataClass를 사용한다.

      - GET 요청을 처리하는 get 메소드와 POST 요청을 처리하는 post 메소드가 구현되어 있다. POST 요청의 경우, Request body와 Response body의 스키마 정보를 생성하고, set_request_body_schema와 set_response_body_schema 메소드를 사용하여 메타데이터에 등록한다. 이후 요청 데이터를 처리하고 응답을 반환한다.

      - 이와 같이 DRF-schema-adapter를 사용하면 프론트엔드 프레임워크 및 라이브러리에 스키마 정보를 제공할 수 있다. 필요에 따라 특정 프론트엔드와 함께 작동하기 위해 사용자 정의 어댑터를 작성하거나, 스키마 정보를 JSON 파일로 내보내는 기능을 활용할 수도 있다.

 

- 공식 사이트 문서 : https://www.django-rest-framework.org/api-guide/metadata/

Metadata - Django REST framework