[DRF] Settings

강민성·2024년 10월 2일

Django REST framework django drf

DRF API Guide

목록 보기

28/28

설정 (Settings)

네임스페이스는 정말 훌륭한 아이디어죠. 더 많이 활용해봅시다!
— The Zen of Python

REST framework의 설정은 모두 단일 Django 설정 내에 네임스페이스화되어 있으며, REST_FRAMEWORK라는 이름의 설정에 포함됩니다.

예를 들어, 프로젝트의 settings.py 파일에 아래와 같은 내용이 있을 수 있습니다:

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
    ],
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework.parsers.JSONParser',
    ]
}

설정 접근 (Accessing settings)

프로젝트에서 REST framework의 API 설정 값을 사용해야 한다면, api_settings 객체를 사용해야 합니다. 예를 들어:

from rest_framework.settings import api_settings

print(api_settings.DEFAULT_AUTHENTICATION_CLASSES)

api_settings 객체는 사용자가 정의한 설정을 확인한 뒤, 그렇지 않을 경우 기본 값을 사용합니다. 클래스 참조를 위한 문자열 경로를 사용하는 설정은 해당 문자열 대신 참조된 클래스를 자동으로 가져와 반환합니다.

API 레퍼런스

API 정책 설정 (API policy settings)

다음 설정들은 기본 API 정책을 제어하며, 모든 APIView 클래스 기반 뷰 또는 @api_view 함수 기반 뷰에 적용됩니다.

DEFAULT_RENDERER_CLASSES
응답 객체를 반환할 때 사용할 기본 렌더러의 목록 또는 튜플입니다.

기본값:

[
    'rest_framework.renderers.JSONRenderer',
    'rest_framework.renderers.BrowsableAPIRenderer',
]

DEFAULT_PARSER_CLASSES
request.data 속성에 접근할 때 사용할 기본 파서의 목록 또는 튜플입니다.

기본값:

[
    'rest_framework.parsers.JSONParser',
    'rest_framework.parsers.FormParser',
    'rest_framework.parsers.MultiPartParser'
]

DEFAULT_AUTHENTICATION_CLASSES
request.user 또는 request.auth 속성에 접근할 때 사용할 기본 인증 클래스의 목록 또는 튜플입니다.

기본값:

[
    'rest_framework.authentication.SessionAuthentication',
    'rest_framework.authentication.BasicAuthentication'
]

DEFAULT_PERMISSION_CLASSES
뷰의 시작 시 확인할 기본 권한 클래스의 목록 또는 튜플입니다. 목록에 있는 모든 클래스에 의해 권한이 부여되어야 합니다.

기본값:

[
    'rest_framework.permissions.AllowAny',
]

DEFAULT_THROTTLE_CLASSES
뷰의 시작 시 확인할 기본 쓰로틀 클래스의 목록 또는 튜플입니다.

기본값: []

DEFAULT_CONTENT_NEGOTIATION_CLASS
응답에 대한 렌더러를 선택할 때 사용할 콘텐츠 협상 클래스를 지정합니다.

기본값: 'rest_framework.negotiation.DefaultContentNegotiation'

DEFAULT_SCHEMA_CLASS
스키마 생성을 위해 사용할 뷰 검사 클래스를 지정합니다.

기본값: 'rest_framework.schemas.openapi.AutoSchema'

제네릭 뷰 설정 (Generic view settings)

다음 설정들은 제네릭 클래스 기반 뷰의 동작을 제어합니다.

DEFAULT_FILTER_BACKENDS
제네릭 필터링에 사용할 필터 백엔드 클래스의 목록입니다. None으로 설정되면 제네릭 필터링이 비활성화됩니다.

DEFAULT_PAGINATION_CLASS
쿼리셋 페이징에 사용할 기본 클래스를 지정합니다. None으로 설정하면 기본적으로 페이징이 비활성화됩니다. 페이징 스타일 설정 및 수정에 대한 추가 정보는 pagination documentation를 참조하세요.

기본값: None

PAGE_SIZE
페이징에 사용할 기본 페이지 크기를 지정합니다. None으로 설정되면 기본적으로 페이징이 비활성화됩니다.

기본값: None

SEARCH_PARAM
검색 필터에서 사용할 검색어를 지정할 쿼리 매개변수의 이름입니다.

기본값: search

ORDERING_PARAM
정렬 필터에서 반환된 결과의 정렬 기준을 지정할 쿼리 매개변수의 이름입니다.

기본값: ordering

버전 관리 설정 (Versioning settings)

DEFAULT_VERSION
버전 관리 정보가 없을 때 request.version에 사용할 기본값입니다.

기본값: None

ALLOWED_VERSIONS
설정된 경우, 버전 관리 체계에서 반환할 수 있는 버전의 집합을 제한하며, 제공된 버전이 이 집합에 속하지 않을 경우 오류를 발생시킵니다.

기본값: None

VERSION_PARAM
미디어 타입 또는 URL 쿼리 매개변수에서 사용할 버전 매개변수의 문자열입니다.

기본값: version

DEFAULT_VERSIONING_CLASS
기본적으로 사용할 버전 관리 체계를 지정합니다.

기본값: None

인증 설정 (Authentication settings)

다음 설정들은 인증되지 않은 요청의 동작을 제어합니다.

UNAUTHENTICATED_USER
인증되지 않은 요청에 대해 request.user를 초기화할 때 사용할 클래스를 지정합니다. (예: django.contrib.auth를 INSTALLED_APPS에서 제거하여 인증을 완전히 제거하려는 경우, UNAUTHENTICATED_USER를 None으로 설정합니다.)

기본값: django.contrib.auth.models.AnonymousUser

UNAUTHENTICATED_TOKEN
인증되지 않은 요청에 대해 request.auth를 초기화할 때 사용할 클래스를 지정합니다.

기본값: None

테스트 설정 (Test settings)

다음 설정들은 APIRequestFactory 및 APIClient의 동작을 제어합니다.

TEST_REQUEST_DEFAULT_FORMAT
테스트 요청을 만들 때 사용할 기본 형식을 지정합니다.

이 형식은 TEST_REQUEST_RENDERER_CLASSES 설정에서 지원되는 렌더러 클래스 중 하나의 형식과 일치해야 합니다.

기본값: 'multipart'

TEST_REQUEST_RENDERER_CLASSES
테스트 요청을 만들 때 지원되는 렌더러 클래스 목록입니다.

이 렌더러 클래스 중 하나의 형식을 사용하여 테스트 요청을 구성할 수 있습니다. 예를 들어: client.post('/users', {'username': 'jamie'}, format='json')

기본값:

[
    'rest_framework.renderers.MultiPartRenderer',
    'rest_framework.renderers.JSONRenderer'
]

스키마 생성 제어 (Schema generation controls)

SCHEMA_COERCE_PATH_PK
설정된 경우, 스키마 경로 매개변수를 생성할 때 URL 설정의 pk 식별자를 실제 필드 이름(일반적으로 id)으로 매핑합니다. "primary key"는 구현 세부 사항이므로, "identifier"라는 보다 일반적인 개념을 표현하는 데 적합합니다.

기본값: True

SCHEMA_COERCE_METHOD_NAMES
설정된 경우, 내부적으로 사용되는 ViewSet 메서드 이름을 스키마 생성 시 사용할 외부 액션 이름으로 매핑합니다. 이를 통해 코드베이스에서 내부적으로 사용되는 것보다 외부 표현에 더 적합한 이름을 생성할 수 있습니다.

기본값: {'retrieve': 'read', 'destroy': 'delete'}

콘텐츠 유형 제어

URL_FORMAT_OVERRIDE
URL에 format=… 쿼리 매개변수를 사용하여 기본 콘텐츠 협상 수락 헤더 동작을 재정의할 수 있는 URL 매개변수의 이름입니다.

예시: http://example.com/organizations/?format=csv

이 설정의 값이 None인 경우 URL 형식 재정의는 비활성화됩니다.

기본값: 'format'

FORMAT_SUFFIX_KWARG
형식 접미사를 제공하기 위해 URL 구성에서 사용할 수 있는 매개변수의 이름입니다. 이 설정은 format_suffix_patterns를 사용하여 접미사 URL 패턴을 포함할 때 적용됩니다.

예시: http://example.com/organizations.csv/

기본값: 'format'

날짜 및 시간 형식

다음 설정은 날짜 및 시간 표현을 파싱하고 렌더링하는 방식을 제어하는 데 사용됩니다.

DATETIME_FORMAT
DateTimeField 직렬화 필드의 출력 렌더링에 기본적으로 사용될 형식 문자열입니다. None인 경우, DateTimeField 직렬화 필드는 Python의 datetime 객체를 반환하며, 날짜 및 시간 인코딩은 렌더러에 의해 결정됩니다.

None, 'iso-8601', 또는 Python strftime 형식 문자열 중 하나일 수 있습니다.

기본값: 'iso-8601'

DATETIME_INPUT_FORMATS
DateTimeField 직렬화 필드의 입력을 파싱할 때 기본적으로 사용되는 형식 문자열 목록입니다.

이 목록에는 'iso-8601' 문자열이나 Python strftime 형식 문자열이 포함될 수 있습니다.

기본값: ['iso-8601']

DATE_FORMAT
DateField 직렬화 필드의 출력 렌더링에 기본적으로 사용될 형식 문자열입니다. None인 경우, DateField 직렬화 필드는 Python의 date 객체를 반환하며, 날짜 인코딩은 렌더러에 의해 결정됩니다.

None, 'iso-8601', 또는 Python strftime 형식 문자열 중 하나일 수 있습니다.

기본값: 'iso-8601'

DATE_INPUT_FORMATS
DateField 직렬화 필드의 입력을 파싱할 때 기본적으로 사용되는 형식 문자열 목록입니다.

이 목록에는 'iso-8601' 문자열이나 Python strftime 형식 문자열이 포함될 수 있습니다.

기본값: ['iso-8601']

TIME_FORMAT
TimeField 직렬화 필드의 출력 렌더링에 기본적으로 사용될 형식 문자열입니다. None인 경우, TimeField 직렬화 필드는 Python의 time 객체를 반환하며, 시간 인코딩은 렌더러에 의해 결정됩니다.

None, 'iso-8601', 또는 Python strftime 형식 문자열 중 하나일 수 있습니다.

기본값: 'iso-8601'

TIME_INPUT_FORMATS
TimeField 직렬화 필드의 입력을 파싱할 때 기본적으로 사용되는 형식 문자열 목록입니다.

이 목록에는 'iso-8601' 문자열이나 Python strftime 형식 문자열이 포함될 수 있습니다.

기본값: ['iso-8601']

인코딩

UNICODE_JSON
True로 설정되면, JSON 응답에서 유니코드 문자를 허용합니다. 예시:

{"unicode black star": "★"}
False로 설정되면, JSON 응답에서 비-ASCII 문자를 이스케이프합니다. 예시:

{"unicode black star": "\u2605"}
두 형식 모두 RFC 4627에 맞으며, 구문적으로 유효한 JSON입니다. 유니코드 스타일은 API 응답을 검사할 때 더 사용자 친화적이므로 권장됩니다.

기본값: True

COMPACT_JSON
True로 설정되면, JSON 응답이 간결한 형태로 반환되며, : 및 , 문자 뒤에 공백이 없습니다. 예시:

{"is_admin": false, "email": "jane@example"}
False로 설정되면, JSON 응답이 약간 더 긴 형태로 반환됩니다. 예시:

{"is_admin": false, "email": "jane@example"}
기본 스타일은 Heroku의 API 설계 지침에 따라 최소화된 응답을 반환하는 것입니다.

기본값: True

STRICT_JSON
True로 설정되면, JSON 렌더링 및 파싱은 JSON의 구문적으로 유효한 값만을 준수하며, Python의 json 모듈에서 허용하는 확장된 실수 값(nan, inf, -inf)에 대해 예외를 발생시킵니다. 이는 권장 설정입니다. 이러한 값은 일반적으로 지원되지 않기 때문입니다. 예를 들어, JavaScript의 JSON.Parse나 PostgreSQL의 JSON 데이터 타입은 이러한 값을 허용하지 않습니다.

False로 설정되면, JSON 렌더링 및 파싱은 허용적입니다. 그러나 이러한 값은 여전히 유효하지 않으며 코드에서 특별히 처리해야 합니다.

기본값: True

COERCE_DECIMAL_TO_STRING
API 표현에서 네이티브 소수점 유형을 지원하지 않는 경우 소수점 값을 문자열로 반환하는 것이 일반적으로 가장 좋습니다. 이는 이진 부동소수점 구현에서 발생하는 정밀도 손실을 방지합니다.

True로 설정되면, 직렬화기의 DecimalField 클래스는 Decimal 객체 대신 문자열을 반환합니다. False로 설정되면, 직렬화기는 Decimal 객체를 반환하며, 기본 JSON 인코더는 이를 부동소수점으로 반환합니다.

기본값: True

뷰 이름 및 설명

다음 설정은 OPTIONS 요청에 대한 응답 및 브라우저에서 사용되는 API에 대한 뷰 이름과 설명을 생성하는 데 사용됩니다.

VIEW_NAME_FUNCTION
뷰 이름을 생성할 때 사용할 함수의 문자열을 나타냅니다.

다음과 같은 서명을 가진 함수여야 합니다:

view_name(self)
self: 뷰 인스턴스입니다. 일반적으로 이름 함수는 클래스 이름을 참조하여 설명 이름을 생성하기 위해 self.__class__.__name__을 참조합니다.
뷰 인스턴스가 ViewSet을 상속받으면, 다음과 같은 선택적 인수로 초기화될 수 있습니다:

name: 뷰에 명시적으로 제공된 이름. 일반적으로 제공된 그대로 사용해야 합니다.
suffix: 뷰셋에서 개별 뷰를 구분할 때 사용되는 텍스트. 이 인수는 name과 상호 배타적입니다.
detail: 개별 뷰가 '목록' 또는 '세부 사항' 뷰인지 구분하는 부울 값입니다.

기본값: 'rest_framework.views.get_view_name'

VIEW_DESCRIPTION_FUNCTION
뷰 설명을 생성할 때 사용할 함수의 문자열을 나타냅니다.

이 설정은 기본 마크다운 외의 마크업 스타일을 지원하도록 변경할 수 있습니다. 예를 들어, 뷰 문서 문자열에서 rst 마크업을 지원하도록 변경할 수 있습니다.

다음과 같은 서명을 가진 함수여야 합니다:

view_description(self, html=False)
self: 뷰 인스턴스입니다. 일반적으로 설명 함수는 클래스의 문서 문자열을 참조하여 설명을 생성하기 위해 self.__class__.__doc__을 참조합니다.
html: HTML 출력을 요구하는지 여부를 나타내는 부울 값입니다. 브라우저 API에서 사용할 때는 True, OPTIONS 응답을 생성할 때는 False입니다.

기본값: 'rest_framework.views.get_view_description'

HTML 선택 필드 한도

브라우저 API에서 관계 필드를 렌더링할 때 선택 필드 한도에 대한 전역 설정입니다.

HTML_SELECT_CUTOFF
html_cutoff 값에 대한 전역 설정입니다. 정수여야 합니다.

기본값: 1000

HTML_SELECT_CUTOFF_TEXT
html_cutoff_text에 대한 전역 설정을 나타내는 문자열입니다.

기본값: "More than {count} items..."

기타 설정

EXCEPTION_HANDLER
어떤 예외에 대해 응답을 반환할 때 사용할 함수의 문자열을 나타냅니다. 함수가 None을 반환하면 500 오류가 발생합니다.

이 설정은 기본적으로 {"detail": "실패..."}와 같은 응답 대신 다른 오류 응답을 지원하도록 변경할 수 있습니다. 예를 들어, {"errors": [{"message": "실패...", "code": ""} ...]}와 같은 API 응답을 제공할 수 있습니다.

다음과 같은 서명을 가진 함수여야 합니다:

exception_handler(exc, context)
exc: 예외입니다.
기본값: 'rest_framework.views.exception_handler'

NON_FIELD_ERRORS_KEY
특정 필드를 참조하지 않고 일반적인 오류를 반환할 때 사용하는 키입니다.

기본값: 'non_field_errors'

URL_FIELD_NAME
HyperlinkedModelSerializer에 의해 만들어진 URL 필드를 위해 사용되는 키입니다.

기본값: url

NUM_PROXIES
API가 실행되는 앱의 프록시 수를 나타내는 0 이상의 정수입니다. 이는 쓰로틀링이 사용자의 IP 주소를 보다 정확하게 식별할 수 있게 해줍니다. 만약 None으로 설정된 경우 쓰로틀 클래스에서는 비교적 덜 엄격한 IP 매칭이 이루어질 것입니다.

기본값: None

Reference

DRF API Guide - Settings

강민성

Back-end Junior Developer

이전 포스트

[DRF] Settings

DRF API Guide

설정 (Settings)

설정 접근 (Accessing settings)

API 레퍼런스

API 정책 설정 (API policy settings)

제네릭 뷰 설정 (Generic view settings)

버전 관리 설정 (Versioning settings)

인증 설정 (Authentication settings)

테스트 설정 (Test settings)

스키마 생성 제어 (Schema generation controls)

콘텐츠 유형 제어

날짜 및 시간 형식

인코딩

뷰 이름 및 설명

HTML 선택 필드 한도

기타 설정

Reference

[DRF] Testing

0개의 댓글