[DRF] Metadata

강민성·2024년 9월 29일

DRF API Guide

목록 보기

21/28

메타데이터

OPTIONS 메서드는 리소스와 관련된 옵션 또는 요구 사항을 결정하거나, 리소스 작업을 암시하거나 리소스를 가져오는 작업을 시작하지 않고 서버의 기능을 파악할 수 있게 해줍니다.
— RFC7231, 섹션 4.3.7.

REST 프레임워크에는 API가 OPTIONS 요청에 어떻게 응답할지 결정하는 설정 가능한 메커니즘이 포함되어 있습니다. 이를 통해 API 스키마나 다른 리소스 정보를 반환할 수 있습니다.

현재 HTTP OPTIONS 요청에 대해 어떤 스타일의 응답이 반환되어야 하는지에 대한 널리 채택된 규칙은 없습니다. 따라서 유용한 정보를 반환하는 임시(ad-hoc) 스타일을 제공합니다.

다음은 기본적으로 반환되는 정보를 보여주는 예시 응답입니다.

HTTP 200 OK  
Allow: GET, POST, HEAD, OPTIONS  
Content-Type: application/json

{
    "name": "할 일 목록",
    "description": "기존 '할 일' 항목을 나열하거나 새 항목을 생성합니다.",
    "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 프레임워크 패키지에는 SimpleMetadata라는 하나의 메타데이터 클래스 구현만 포함되어 있습니다. 다른 스타일을 사용하려면 커스텀 메타데이터 클래스를 구현해야 합니다.

스키마 엔드포인트 생성

정규 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):
    """
    `OPTIONS` 요청에 대해 필드 및 기타 정보를 포함하지 않습니다.
    이름과 설명만 반환합니다.
    """
    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는 프론트엔드 프레임워크와 라이브러리로 스키마 정보를 제공하는 것을 더 쉽게 만들어주는 도구 세트입니다. 이 패키지는 메타데이터 믹스인과 두 개의 메타데이터 클래스, 다양한 라이브러리가 읽을 수 있는 JSON 스키마 및 스키마 정보를 생성하는 여러 어댑터를 제공합니다.

또한 특정 프론트엔드와 작업하기 위한 어댑터를 작성할 수도 있습니다. 그렇게 하려면 스키마 정보를 JSON 파일로 내보낼 수 있는 익스포터도 제공합니다.