[DRF] 공식 문서 - Settings 정리
1. Settings
- REST 프레임워크의 설정은 모두 단일 Django 설정인 REST_FRAMEWORK라는 네임스페이스 안에 있다.
- 예를 들어, 프로젝트의 settings.py 파일에는 다음과 같은 내용이 포함될 수 있다.
REST_FRAMEWORK = {
'DEFAULT_RENDERER_CLASSES': [
'rest_framework.renderers.JSONRenderer',
],
'DEFAULT_PARSER_CLASSES': [
'rest_framework.parsers.JSONParser',
]
}
1) 설정에 접근하기(Accessing settings)
- 프로젝트에서 REST 프레임워크의 API 설정 값을 사용해야 한다면, api_settings 객체를 사용해야 한다.
from rest_framework.settings import api_settings
print(api_settings.DEFAULT_AUTHENTICATION_CLASSES)
- api_settings 객체는 사용자가 정의한 설정을 확인하고, 그렇지 않으면 기본 값으로 돌아간다. 클래스를 참조하기 위해 문자열 가져오기 경로를 사용하는 모든 설정은 문자열 리터럴 대신에 자동으로 참조된 클래스를 가져와서 반환한다.
2. API Reference
1) API 정책 설정(API policy settings)
- 다음 설정들은 기본 API 정책을 제어하며, 모든 APIView 클래스 기반 뷰나 @api_view 함수 기반 뷰에 적용된다.
1. DEFAULT_RENDERER_CLASSES
- DEFAULT_RENDERER_CLASSES는 Response 객체를 반환할 때 사용할 수 있는 기본 렌더러 집합을 결정하는 렌더러 클래스의 리스트 또는 튜플이다.
- Default:
[
'rest_framework.renderers.JSONRenderer',
'rest_framework.renderers.BrowsableAPIRenderer',
]
2. DEFAULT_PARSER_CLASSES
- 요청 데이터를 접근할 때 사용하는 기본 파서 집합을 결정하는 파서 클래스의 리스트 또는 튜플이다.
- Default:
[
'rest_framework.parsers.JSONParser',
'rest_framework.parsers.FormParser',
'rest_framework.parsers.MultiPartParser'
]
3. DEFAULT_AUTHENTICATION_CLASSES
- request.user 또는 request.auth 속성에 접근할 때 사용하는 기본 인증기 집합을 결정하는 인증 클래스의 리스트 또는 튜플이다.
- Default:
[
'rest_framework.authentication.SessionAuthentication',
'rest_framework.authentication.BasicAuthentication'
]
4. DEFAULT_PERMISSION_CLASSES
- DEFAULT_PERMISSION_CLASSES뷰를 시작할 때 확인하는 기본 권한 집합을 결정하는 권한 클래스의 리스트 또는 튜플이다. 리스트에 있는 모든 클래스에 의해 권한이 부여되어야 한다.
- Default:
[
'rest_framework.permissions.AllowAny',
]
5. DEFAULT_THROTTLE_CLASSES
- 뷰를 시작할 때 확인하는 기본 쓰로틀(제한 기능) 집합을 결정하는 쓰로틀 클래스의 리스트 또는 튜플이다.
- Default: [ ]
6. DEFAULT_CONTENT_NEGOTIATION_CLASS
- 콘텐츠 협상 클래스는 들어오는 요청에 대해 응답에 렌더러가 어떻게 선택되는지를 결정한다.
- Default: 'rest_framework.negotiation.DefaultContentNegotiation'
7. DEFAULT_SCHEMA_CLASS
- 스키마 생성에 사용될 뷰 검사기 클래스이다.
- Default: 'rest_framework.schemas.openapi.AutoSchema'
2) 일반 뷰 설정(Generic view settings)
- 다음 설정들은 일반 클래스 기반 뷰의 동작을 제어한다.
1. DEFAULT_FILTER_BACKENDS
- 일반 필터링에 사용해야 하는 필터 백엔드 클래스의 리스트로 None으로 설정하면 일반 필터링이 비활성화 된다.
2. DEFAULT_PAGINATION_CLASS
- 쿼리셋 페이징에 사용할 기본 클래스이다. None으로 설정하면 기본적으로 페이징이 비활성화 된다. 페이징 스타일을 설정하고 수정하는 방법에 대한 자세한 가이드는 페이징 문서를 참조하면 된다.
- setting : https://www.django-rest-framework.org/api-guide/pagination/#setting-the-pagination-style
- modifying : https://www.django-rest-framework.org/api-guide/pagination/#modifying-the-pagination-style
- Default: None
3. PAGE_SIZE
- 페이징에 사용할 기본 페이지 크기이다. None으로 설정하면 기본적으로 페이징이 비활성화 된다.
- Default: None
4. SEARCH_PARAM
- SearchFilter에 의해 사용되는 검색어를 지정할 수 있는 쿼리 파라미터의 이름이다.
- Default: search
5. ORDERING_PARAM
- OrderingFilter에 의해 반환되는 결과의 정렬을 지정할 수 있는 쿼리 파라미터의 이름이다.
- Default: ordering
3) 버전 관리 설정(Versioning settings)
1. DEFAULT_VERSION
- 버전 정보가 없을 때 request.version에 사용해야 하는 값이다.
- Default: None
2. ALLOWED_VERSIONS
- 설정되면, 이 값은 버전화 스키마에 의해 반환될 수 있는 버전의 집합을 제한하며, 제공된 버전이 이 집합에 없는 경우 오류를 발생시킨다.
- Default: None
3. VERSION_PARAM
- 미디어 타입이나 URL 쿼리 파라미터 등의 버전화 파라미터에 사용해야 하는 문자열이다.
- Default: 'version'
4. DEFAULT_VERSIONING_CLASS
- 사용해야 하는 기본 버전화 스키마이다.
- Default: None
4) 인증 설정(Authentication settings)
- 다음 설정들은 인증되지 않은 요청의 동작을 제어한다.
1. UNAUTHENTICATED_USER
- 인증되지 않은 요청에 대해 request.user를 초기화하는 데 사용해야 하는 클래스이다. (예를 들어, django.contrib.auth를 INSTALLED_APPS에서 제거함으로써 인증을 완전히 제거하는 경우, UNAUTHENTICATED_USER를 None으로 설정하자.)
- Default: django.contrib.auth.models.AnonymousUser
2. UNAUTHENTICATED_TOKEN
- 인증되지 않은 요청에 대해 request.auth를 초기화하는 데 사용해야 하는 클래스이다.
- Default: None
5) 테스트 설정(Test settings)
- 다음 설정들은 APIRequestFactory와 APIClient의 동작을 제어한다.
1. TEST_REQUEST_DEFAULT_FORMAT
- 테스트 요청을 만들 때 사용해야 하는 기본 형식이다.
- 이는 TEST_REQUEST_RENDERER_CLASSES 설정의 렌더러 클래스 중 하나의 형식과 일치해야 한다.
- Default: 'multipart'
2. TEST_REQUEST_RENDERER_CLASSES
- 테스트 요청을 구성할 때 지원되는 렌더러 클래스이다.
- 이러한 렌더러 클래스 중 어떤 형식이든 테스트 요청을 구성할 때 사용될 수 있다.
- 예를 들어: client.post('/users', {'username': 'jamie'}, format='json')
- Default:
[
'rest_framework.renderers.MultiPartRenderer',
'rest_framework.renderers.JSONRenderer'
]
6) 스키마 생성 컨트롤(Schema generation controls)
1. SCHEMA_COERCE_PATH_PK
- 설정하면, 이는 URL conf의 'pk' 식별자를 스키마 경로 매개변수를 생성할 때 실제 필드 이름에 매핑한다. 일반적으로 이는 'id'가 될 것이다. 이는 "기본 키"가 구현 세부사항인 반면 "식별자"는 더 일반적인 개념이므로 더 적합한 표현을 제공한다.
- Default: True
2. SCHEMA_COERCE_METHOD_NAMES
- 설정하면, 이는 내부 viewset 메소드 이름을 스키마 생성에 사용되는 외부 액션 이름에 매핑하는 데 사용된다. 이를 통해 코드베이스 내부에서 사용되는 것보다 외부 표현에 더 적합한 이름을 생성할 수 있다.
- Default: {'retrieve': 'read', 'destroy': 'delete'}
7) 콘텐츠 유형 컨트롤(Content type controls)
1. URL_FORMAT_OVERRIDE
- 요청 URL의 format=… 쿼리 파라미터를 사용하여 기본 콘텐츠 협상 Accept 헤더 동작을 재정의할 수 있는 URL 파라미터의 이름이다.
- 예를 들어: http://example.com/organizations/?format=csv
- 이 설정의 값이 None이면 URL 형식 재정의가 비활성화 된다.
- Default: 'format'
2. FORMAT_SUFFIX_KWARG
- 형식 접미사를 제공하는 데 사용할 수 있는 URL conf의 파라미터 이름이다. 이 설정은 suffixed URL 패턴을 포함하기 위해 format_suffix_patterns를 사용할 때 적용된다.
- 예를 들어: http://example.com/organizations.csv/
- Default: 'format'
8) 날짜와 시간 형식(Date and time formatting)
- 다음 설정들은 날짜와 시간 표현이 어떻게 파싱되고 렌더링될 수 있는지를 제어하는 데 사용된다.
1. DATETIME_FORMAT
- DateTimeField serializer 필드의 출력을 렌더링하는 데 기본적으로 사용해야 하는 형식 문자열이다. None인 경우, DateTimeField serializer 필드는 Python datetime 객체를 반환하며, datetime 인코딩은 렌더러에 의해 결정된다.
- None, 'iso-8601' 또는 Python strftime 형식 문자열 중 어느 것이든 될 수 있습니다.
- Default: 'iso-8601'
2. DATETIME_INPUT_FORMATS
- DateTimeField serializer 필드로의 입력을 파싱하는 데 기본적으로 사용해야 하는 형식 문자열의 리스트이다.
- 'iso-8601' 문자열 또는 Python strftime 형식 문자열을 포함하는 리스트일 수 있습니다.
- - Default: ['iso-8601']
3. DATE_FORMAT
- DateField serializer 필드의 출력을 렌더링하는 데 기본적으로 사용해야 하는 형식 문자열이다. None인 경우, DateField serializer 필드는 Python date 객체를 반환하며, date 인코딩은 렌더러에 의해 결정된다.
- None, 'iso-8601' 또는 Python strftime 형식 문자열 중 어느 것이든 될 수 있다.
- Default: 'iso-8601'
4. DATE_INPUT_FORMATS
- DateField serializer 필드로의 입력을 파싱하는 데 기본적으로 사용해야 하는 형식 문자열의 리스트이다.
- 'iso-8601' 문자열 또는 Python strftime 형식 문자열을 포함하는 리스트일 수 있다.
- Default: ['iso-8601']
5. TIME_FORMAT
- TimeField serializer 필드의 출력을 렌더링하는 데 기본적으로 사용해야 하는 형식 문자열이다. None인 경우, TimeField serializer 필드는 Python time 객체를 반환하며, time 인코딩은 렌더러에 의해 결정된다.
- None, 'iso-8601' 또는 Python strftime 형식 문자열 중 어느 것이든 될 수 있다.
- Default: 'iso-8601'
6. TIME_INPUT_FORMATS
- TimeField serializer 필드로의 입력을 파싱하는 데 기본적으로 사용해야 하는 형식 문자열의 리스트이다.
- 'iso-8601' 문자열 또는 Python strftime 형식 문자열을 포함하는 리스트일 수 있다.
- Default: ['iso-8601']
9) Encodings
1. UNICODE_JSON
- True로 설정하면, JSON 응답에서 유니코드 문자를 허용한다.
{"unicode black star":"★"}
- False로 설정하면, JSON 응답은 비-아스키 문자를 이스케이프 처리한다.
{"unicode black star":"\u2605"}
- 두 스타일 모두 RFC 4627을 준수하며, 구문적으로 유효한 JSON이다. 유니코드 스타일은 API 응답을 검사할 때 더 사용자 친화적이라는 점에서 선호된다.
- Default: True
2. COMPACT_JSON
- True로 설정하면, JSON 응답은 ':' 및 ',' 문자 뒤에 공백 없이 축약된 표현을 반환한다.
{"is_admin":false,"email":"jane@example"}
- False로 설정하면, JSON 응답은 약간 더 자세한 표현을 반환한다.
{"is_admin": false, "email": "jane@example"}
- 기본 스타일은 Heroku의 API 디자인 가이드라인에 따라 축소된 응답을 반환하는 것이다.
- Default: True
3. STRICT_JSON
- True로 설정하면, JSON 렌더링과 파싱은 구문적으로 유효한 JSON만을 인식하며, Python의 json 모듈에서 허용하는 확장 float 값(nan, inf, -inf)에 대해 예외를 발생시킨다. 이러한 값이 일반적으로 지원되지 않기 때문에, 이 설정이 권장된다. 예를 들어, Javascript의 JSON.Parse나 PostgreSQL의 JSON 데이터 타입은 이러한 값을 수용하지 않는다.
- False로 설정하면, JSON 렌더링과 파싱은 관대하게 된다. 그러나 이러한 값들은 여전히 유효하지 않으므로 코드에서 특별히 처리해야 한다.
- Default: True
4. COERCE_DECIMAL_TO_STRING
- API 표현에서 기본적으로 decimal 타입을 지원하지 않는 decimal 객체를 반환할 때, 일반적으로 값을 문자열로 반환하는 것이 최선이다. 이렇게 하면 이진 부동 소수점 구현에서 발생하는 정밀도 손실을 피할 수 있다.
- True로 설정하면, serializer DecimalField 클래스는 Decimal 객체 대신 문자열을 반환한다. False로 설정하면, serializer는 Decimal 객체를 반환하며, 기본 JSON 인코더는 이를 float로 반환한다.
- Default: True
10) 뷰 이름과 설명(View names and descriptions)
- 다음 설정들은 OPTIONS 요청에 대한 응답과 브라우저 가능한 API에서 사용되는 뷰 이름과 설명을 생성하는 데 사용된다.
1. VIEW_NAME_FUNCTION
- 뷰 이름을 생성할 때 사용해야 하는 함수를 나타내는 문자열이다.
- 이는 다음 서명을 가진 함수여야 한다.
view_name(self)
- self: 뷰 인스턴스이다. 일반적으로 이름 함수는 self.class.__name__에 접근하여 설명적인 이름을 생성할 때 클래스의 이름을 검사한다.
- 만약 뷰 인스턴스가 ViewSet을 상속받았다면, 몇 가지 선택적 인자로 초기화되었을 수 있다.
- name: 뷰셋의 뷰에 명시적으로 제공된 이름이다. 일반적으로, 이 값은 제공될 때 그대로 사용해야 한다.
- suffix: 뷰셋의 개별 뷰를 구별할 때 사용되는 텍스트이다. 이 인자는 name과 상호 배타적이다.
- detail: 뷰셋의 개별 뷰를 'list' 뷰 또는 'detail' 뷰로 구별하는 Boolean이다.
- 기본값: 'rest_framework.views.get_view_name'
2. VIEW_DESCRIPTION_FUNCTION
- 뷰 설명을 생성할 때 사용되어야 하는 함수를 나타내는 문자열이다.
- 이 설정은 기본 마크다운 이외의 마크업 스타일을 지원하도록 변경할 수 있다. 예를 들어, 뷰의 docstrings에 있는 rst 마크업을 브라우저 가능한 API에서 출력하도록 지원할 수 있다.
- 이는 다음 서명을 가진 함수여야 한다.
view_description(self, html=False)
- self: 뷰 인스턴스이다. 일반적으로 설명 함수는 self.class.__doc__에 접근하여 설명을 생성할 때 클래스의 docstring을 검사한다.
- html: HTML 출력이 필요한지 여부를 나타내는 boolean이다. 브라우저 가능한 API에서 사용될 때는 True이고, OPTIONS 응답을 생성할 때는 False이다.
- 만약 뷰 인스턴스가 ViewSet을 상속받았다면, 몇 가지 선택적 인자로 초기화되었을 수 있다.
- description: 뷰셋의 뷰에 명시적으로 제공된 설명이다. 일반적으로, 이는 추가 viewset 동작에 의해 설정되며, 그대로 사용해야 한다.
- detail: 'rest_framework.views.get_view_description'
11) HTML 선택 필드 컷오프(HTML Select Field cutoffs)
- 브라우저 가능한 API에서 관계 필드를 렌더링하기 위한 선택 필드 컷오프에 대한 전역 설정이다.
- select field cutoffs for rendering relational fields : https://www.django-rest-framework.org/api-guide/relations/#select-field-cutoffs
1. HTML_SELECT_CUTOFF
- html_cutoff 값에 대한 전역 설정이다. 이는 반드시 정수여야 한다.
- detail: 1000
2. HTML_SELECT_CUTOFF_TEXT
- html_cutoff_text에 대한 전역 설정을 나타내는 문자열이다.
- detail: "More than {count} items..."
12) 기타 설정(Miscellaneous settings)
1. EXCEPTION_HANDLER
- 주어진 예외에 대한 응답을 반환할 때 사용해야 하는 함수를 나타내는 문자열이다. 함수가 None을 반환하면, 500 오류가 발생한다.
- 이 설정은 기본적인 {"detail": "Failure..."} 응답 외의 오류 응답을 지원하도록 변경할 수 있다. 예를 들어, 이를 사용하여 {"errors": [{"message": "Failure...", "code": ""} ...]}와 같은 API 응답을 제공할 수 있다.
- 이는 다음 서명을 가진 함수여야 한다.
exception_handler(exc, context)
- exc: 예외입니다.
- detail: 'rest_framework.views.exception_handler'
2. NON_FIELD_ERRORS_KEY
- 특정 필드를 참조하지 않지만 일반적인 오류인 serializer 오류에 사용해야 하는 키를 나타내는 문자열이다.
- detail: 'non_field_errors'
3. URL_FIELD_NAME
- HyperlinkedModelSerializer에 의해 생성된 URL 필드에 사용해야 하는 키를 나타내는 문자열이다.
- detail: 'url'
4. NUM_PROXIES
- API가 뒤에서 실행되는 애플리케이션 프록시의 수를 지정하는 데 사용될 수 있는 0 이상의 정수이다. 이를 통해 스로틀링이 클라이언트 IP 주소를 더 정확하게 식별할 수 있다. None으로 설정하면 스로틀 클래스에서 덜 엄격한 IP 매칭이 사용된다.
- detail: None
- 예시 :
- 서버 앞에 위치한 프록시 서버의 개수를 지정하는데 사용된다. 이 설정은 클라이언트의 실제 IP 주소를 정확하게 파악하는 데 중요한 역할을 한다.
- 예를 들어, 우리의 서버가 직접 클라이언트와 연결되지 않고, Nginx와 같은 리버스 프록시를 통해 연결되는 경우가 흔하다. 이때 NUM_PROXIES 설정을 1로 지정하면, DRF는 요청의 실제 출처를 알아내기 위해 HTTP 헤더의 'X-Forwarded-For' 필드를 확인하고, 마지막 IP를 클라이언트의 IP로 인식한다.
- 또한, 서버 앞에 여러 개의 프록시 서버가 있는 경우에도 NUM_PROXIES 설정이 필요하다. 이를 통해 DRF는 'X-Forwarded-For' 헤더에 나열된 IP 주소 중에서 적절한 IP를 클라이언트의 IP로 선택할 수 있다.
- 다음은 NUM_PROXIES 설정을 사용하는 예제 코드이다.
# settings.py
REST_FRAMEWORK = {
'NUM_PROXIES': 2, # 우리의 서버 앞에 2개의 프록시 서버가 있다고 가정합니다.
}# views.py
from rest_framework.views import APIView
from rest_framework.request import Request
from rest_framework.response import Response
class ClientIPView(APIView):
def get(self, request: Request) -> Response:
client_ip = request.META.get('REMOTE_ADDR') # 클라이언트의 IP 주소를 얻습니다.
return Response({'client_ip': client_ip})
- 위의 예제에서 NUM_PROXIES 설정이 2로 지정되어 있으므로, DRF는 'X-Forwarded-For' 헤더에서 뒤에서부터 두 번째 IP 주소를 클라이언트의 IP로 인식하게 된다. 이 IP 주소는 request.META.get('REMOTE_ADDR')를 통해 얻을 수 있다.
- 공식 사이트 문서 : https://www.django-rest-framework.org/api-guide/settings/
Settings - Django REST framework
www.django-rest-framework.org
'Django REST Framework > DRF 일반' 카테고리의 다른 글
| [DRF] 공식 문서 - Exceptions 정리 (0) | 2024.01.22 |
|---|---|
| [DRF] 공식 문서 - Testing 정리 (1) | 2024.01.22 |
| [DRF] 공식 문서 - Permissions 정리 (0) | 2024.01.20 |
| [DRF] 공식 문서 - Authentication 정리 (0) | 2024.01.19 |
| [DRF] 공식 문서 - pagination 정리 (0) | 2024.01.19 |
댓글