클래스 기반 뷰 (Class-based Views)

Django의 클래스 기반 뷰는 이전의 뷰 스타일에서 환영할 만한 변화입니다.
— Reinout van Rees

REST 프레임워크는 Django의 View 클래스를 서브클래싱한 APIView 클래스를 제공합니다.

APIView 클래스는 일반 View 클래스와 다음과 같은 차이점이 있습니다:

• 처리 메서드에 전달되는 요청은 Django의 HttpRequest 인스턴스가 아닌, REST 프레임워크의 Request 인스턴스입니다.
• 처리 메서드는 Django의 HttpResponse 대신 REST 프레임워크의 Response를 반환할 수 있습니다. 이 뷰는 콘텐츠 협상을 관리하고 응답에 올바른 렌더러를 설정합니다.
• 모든 APIException 예외는 포착되어 적절한 응답으로 변환됩니다.
• 들어오는 요청은 인증되며, 요청이 처리 메서드로 전달되기 전에 적절한 권한 및/또는 트로틀(throttle) 검사가 실행됩니다.

APIView 클래스를 사용하는 것은 일반 View 클래스를 사용하는 것과 거의 동일하며, 들어오는 요청은 .get() 또는 .post()와 같은 적절한 처리 메서드로 전달됩니다. 또한, 클래스에는 API 정책의 다양한 측면을 제어하는 여러 속성을 설정할 수 있습니다.

예시:

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework import authentication, permissions
from django.contrib.auth.models import User

class ListUsers(APIView):
    """
    시스템의 모든 사용자를 나열하는 뷰.

    * 토큰 인증이 필요합니다.
    * 이 뷰는 관리자 사용자만 접근할 수 있습니다.
    """
    authentication_classes = [authentication.TokenAuthentication]
    permission_classes = [permissions.IsAdminUser]

    def get(self, request, format=None):
        """
        모든 사용자의 목록을 반환합니다.
        """
        usernames = [user.username for user in User.objects.all()]
        return Response(usernames)

참고: Django REST 프레임워크의 APIView, GenericAPIView, 다양한 믹스인(Mixins), 및 Viewset 간의 관계는 처음에는 복잡할 수 있습니다. 여기의 문서 외에도, Classy Django REST Framework 자료는 각 클래스 기반 뷰의 전체 메서드와 속성에 대한 탐색 가능한 참조 자료를 제공합니다.

---

API 정책 속성

다음 속성은 API 뷰의 플러그 가능(사용자 정의 가능)한 측면을 제어합니다:

• .renderer_classes
• .parser_classes
• .authentication_classes
• .throttle_classes
• .permission_classes
• .content_negotiation_class

API 정책 인스턴스화 메서드

다음 메서드는 REST 프레임워크가 다양한 플러그 가능한 API 정책을 인스턴스화할 때 사용됩니다. 이 메서드를 재정의할 필요는 거의 없습니다.

• .get_renderers(self)
• .get_parsers(self)
• .get_authenticators(self)
• .get_throttles(self)
• .get_permissions(self)
• .get_content_negotiator(self)
• .get_exception_handler(self)

API 정책 구현 메서드

다음 메서드는 처리 메서드로 전달되기 전에 호출됩니다.

• .check_permissions(self, request)
• .check_throttles(self, request)
• .perform_content_negotiation(self, request, force=False)

디스패치 메서드

다음 메서드는 뷰의 .dispatch() 메서드에 의해 직접 호출됩니다. 이 메서드는 .get(), .post(), .put(), .patch() 및 .delete()와 같은 처리 메서드를 호출하기 전후에 발생해야 하는 작업을 수행합니다.

• .initial(self, request, *args, **kwargs)
  처리 메서드가 호출되기 전에 수행해야 하는 작업을 처리합니다. 이 메서드는 권한 및 트로틀 검사를 시행하고, 콘텐츠 협상을 수행하는 데 사용됩니다. 이 메서드를 재정의할 필요는 거의 없습니다.

• .handle_exception(self, exc)
  처리 메서드에서 발생한 모든 예외는 이 메서드로 전달되며, 이는 Response 인스턴스를 반환하거나 예외를 다시 발생시킵니다. 기본 구현은 rest_framework.exceptions.APIException의 하위 클래스 및 Django의 Http404와 PermissionDenied 예외를 처리하여 적절한 오류 응답을 반환합니다. API가 반환하는 오류 응답을 커스터마이징하려면 이 메서드를 서브클래싱해야 합니다.

• .initialize_request(self, request, *args, **kwargs)
  처리 메서드로 전달되는 요청 객체가 일반 Django HttpRequest 대신 Request의 인스턴스인지 확인합니다. 이 메서드를 재정의할 필요는 거의 없습니다.

• .finalize_response(self, request, response, *args, **kwargs)
  처리 메서드에서 반환된 모든 Response 객체가 콘텐츠 협상에 의해 결정된 올바른 콘텐츠 타입으로 렌더링되도록 보장합니다. 이 메서드를 재정의할 필요는 거의 없습니다.

---

함수 기반 뷰 (Function Based Views)

클래스 기반 뷰가 항상 더 나은 해결책이라고 말하는 것은 실수입니다.
— Nick Coghlan

REST 프레임워크는 또한 일반 함수 기반 뷰와 함께 작업할 수 있습니다. REST 프레임워크는 함수 기반 뷰를 감싸는 간단한 데코레이터 세트를 제공하여 이 뷰가 Request 인스턴스를 받도록 하고, Response를 반환할 수 있으며, 요청이 처리되는 방식을 구성할 수 있게 합니다.

@api_view()

@api_view(http_method_names=['GET'])

이 기능의 핵심은 api_view 데코레이터로, 뷰가 응답할 HTTP 메서드 목록을 받습니다. 예를 들어, 수동으로 데이터를 반환하는 간단한 뷰를 작성하는 방법은 다음과 같습니다:

from rest_framework.decorators import api_view
from rest_framework.response import Response

@api_view()
def hello_world(request):
    return Response({"message": "Hello, world!"})

이 뷰는 기본 렌더러, 파서, 인증 클래스 등을 설정에서 사용하는 대로 사용합니다.

기본적으로 GET 메서드만 허용됩니다. 다른 메서드는 "405 Method Not Allowed"로 응답합니다. 이 동작을 변경하려면, 허용할 메서드를 명시적으로 지정할 수 있습니다:

@api_view(['GET', 'POST'])
def hello_world(request):
    if request.method == 'POST':
        return Response({"message": "Got some data!", "data": request.data})
    return Response({"message": "Hello, world!"})

API 정책 데코레이터

기본 설정을 재정의하려면, REST 프레임워크는 추가 데코레이터를 제공하며, 이들은 @api_view 데코레이터 아래에 위치해야 합니다. 예를 들어, 특정 사용자가 하루에 한 번만 이 뷰를 호출할 수 있도록 하는 트로틀을 사용하려면 @throttle_classes 데코레이터를 사용하고, 트로틀 클래스를 전달합니다:

from rest_framework.decorators import api_view, throttle_classes
from rest_framework.throttling import UserRateThrottle

class OncePerDayUserThrottle(UserRateThrottle):
    rate = '1/day'

@api_view(['GET'])
@throttle_classes([OncePerDayUserThrottle])
def view(request):
    return Response({"message": "Hello for today! See you tomorrow!"})

이 데코레이터들은 위에서 설명한 APIView 하위 클래스에서 설정된 속성들과 대응됩니다.

사용 가능한 데코레이터는 다음과 같습니다:

• @renderer_classes(...)
• @parser_classes(...)
• @authentication_classes(...)
• @throttle_classes(...)
• @permission_classes(...)

각 데코레이터는 하나의 인자를 받으며, 이 인자는 클래스 목록 또는 튜플이어야 합니다.

뷰 스키마 데코레이터

함수 기반 뷰의 기본 스키마 생성을 재정의하려면 @schema 데코레이터를 사용할 수 있습니다. 이 데코레이터는 @api_view 데코레이터 아래에 있어야 합니다. 예를 들어:

from rest_framework.decorators import api_view, schema
from rest_framework.schemas import AutoSchema

class CustomAutoSchema(AutoSchema):
    def get_link(self, path, method, base_url):
        # 뷰 내부 조회(인스펙션)를 재정의합니다.

이 데코레이터는 하나의 AutoSchema 인스턴스, AutoSchema 하위 클래스 인스턴스 또는 ManualSchema 인스턴스를 받습니다. 스키마 생성을 제외하려면 None을 전달할 수 있습니다:

@api_view(['GET'])
@schema(None)
def view(request):
    return Response({"message": "Will not appear in schema})

Reference

DRF API Guide - Views