형식 접미사 (Format suffixes)
섹션 6.2.1에서는 콘텐츠 협상(content negotiation)이 항상 사용되어야 한다고 말하지 않습니다.
— Roy Fielding, REST 토론 메일링 리스트
웹 API에서 흔히 사용하는 패턴 중 하나는 URL에 파일 확장자를 추가하여 특정 미디어 타입에 대한 엔드포인트를 제공하는 것입니다. 예를 들어, http://example.com/api/users.json은 JSON 표현을 제공하는 URL입니다.
각 API의 URLconf에 형식 접미사 패턴을 개별적으로 추가하는 것은 오류 발생 가능성이 크고 DRY 원칙에 위배됩니다. 이를 해결하기 위해, REST framework는 이러한 패턴을 URLConf에 쉽게 추가할 수 있는 방법을 제공합니다.
format_suffix_patterns
형식: format_suffix_patterns(urlpatterns, suffix_required=False, allowed=None)
제공된 URL 패턴 각각에 형식 접미사 패턴이 추가된 URL 패턴 목록을 반환합니다.
인자:
- urlpatterns: 필수. URL 패턴 목록입니다.
- suffix_required: 선택 사항. URL에서 접미사가 필수인지 여부를 나타내는 boolean 값입니다. 기본값은 False로, 접미사는 기본적으로 선택 사항입니다.
- allowed: 선택 사항. 유효한 형식 접미사의 리스트 또는 튜플입니다. 제공되지 않으면 와일드카드 형식 접미사 패턴이 사용됩니다.
예시:
from rest_framework.urlpatterns import format_suffix_patterns
from blog import views
urlpatterns = [
path('', views.api_root),
path('comments/', views.comment_list),
path('comments/<int:pk>/', views.comment_detail)
]
urlpatterns = format_suffix_patterns(urlpatterns, allowed=['json', 'html'])format_suffix_patterns을 사용할 때는, 해당 뷰에 'format'이라는 키워드 인수를 추가해야 합니다. 예를 들어:
@api_view(['GET', 'POST'])
def comment_list(request, format=None):
# 기능 수행...혹은 클래스 기반 뷰를 사용할 때:
class CommentList(APIView):
def get(self, request, format=None):
# 기능 수행...
def post(self, request, format=None):
# 기능 수행...사용되는 키워드 인수의 이름은 FORMAT_SUFFIX_KWARG 설정을 통해 수정할 수 있습니다.
또한, format_suffix_patterns는 include URL 패턴 내부로 들어가는 것을 지원하지 않는다는 점을 주의해야 합니다.
i18n_patterns과 함께 사용하기
Django에서 제공하는 i18n_patterns 함수와 format_suffix_patterns를 함께 사용하는 경우, i18n_patterns 함수는 최종 또는 가장 바깥쪽 함수로 적용되어야 합니다. 예를 들어:
urlpatterns = [
…
]
urlpatterns = i18n_patterns(
format_suffix_patterns(urlpatterns, allowed=['json', 'html'])
)쿼리 파라미터 형식 (Query parameter formats)
형식 접미사에 대한 대안으로, 요청된 형식을 쿼리 파라미터에 포함할 수 있습니다. REST framework는 기본적으로 이 옵션을 제공하며, 브라우저에서 제공하는 API에서 서로 다른 가용 표현 형식 간의 전환에 사용됩니다.
단축 형식을 사용해 표현 형식을 선택하려면 format 쿼리 파라미터를 사용하십시오. 예를 들어: http://example.com/organizations/?format=csv.
이 쿼리 파라미터의 이름은 URL_FORMAT_OVERRIDE 설정을 통해 수정할 수 있습니다. 이 동작을 비활성화하려면 값을 None으로 설정하면 됩니다.
Accept 헤더 vs 형식 접미사 (Accept headers vs. format suffixes)
웹 커뮤니티 중 일부는 파일 확장자가 RESTful 패턴이 아니며, 항상 HTTP Accept 헤더를 사용해야 한다는 견해를 갖고 있는 것 같습니다.
이는 사실 오해입니다. 예를 들어, Roy Fielding이 쿼리 매개변수를 통한 미디어 타입 표시와 파일 확장자를 통한 미디어 타입 표시의 상대적 장점을 논의하면서 한 다음과 같은 발언을 참고해 보십시오:
"그래서 나는 항상 확장자를 선호합니다. 두 가지 선택 모두 REST와는 상관이 없습니다."
— Roy Fielding, REST 토론 메일링 리스트
이 인용문은 Accept 헤더에 대해 언급하고 있지는 않지만, 형식 접미사가 허용 가능한 패턴으로 여겨져야 한다는 것을 분명히 하고 있습니다.
Reference
