URI 템플릿 완벽 가이드: RFC 6570 마스터하기

RESTful API를 구축할 때 가장 중요한 개념 중 하나는 URI를 사용하여 리소스를 표현하는 방법입니다. URL을 하드코딩하는 것은 유연성이 떨어지며 유지관리의 어려움을 초래합니다. **RFC 6570 (URI Template)**은 최종 URI로 확장될 수 있는 자리 표시자(placeholder)를 사용하여 URI를 설명하는 표준화된 방법을 제공합니다.

이 가이드에서는 URI 템플릿의 작동 원리, 다양한 표현식 유형, 그리고 현대 웹 개발에서 왜 중요한지에 대해 심층적으로 다루어 보겠습니다.

---

URI 템플릿이란 무엇인가요?

URI 템플릿은 중괄호 {}로 묶인 변수를 포함하는 문자열입니다. 이러한 변수는 **Expansion (확장)**이라는 과정을 통해 실제 값으로 대체됩니다.

기본 예시:

템플릿: http://api.example.com/users/{id} 변수: { "id": "123" } 확장 결과: http://api.example.com/users/123

---

URI 템플릿의 8단계 수준

RFC 6570은 확장의 복잡도에 따라 여러 수준을 정의합니다. 가장 일반적인 유형은 다음과 같습니다.

1. 단순 문자열 확장 {var}

단순한 경로 세그먼트에 사용됩니다.

• 템플릿: /{var}
• 값: {"var": "value"}
• 결과: /value

2. 예약어 문자 확장 {+var}

단순 확장과 유사하지만, 퍼센트 인코딩 없이 예약어 문자(/, ?, # 등)를 허용합니다.

• 템플릿: /{+path}/index.html
• 값: {"path": "foo/bar"}
• 결과: /foo/bar/index.html

3. 프래그먼트 확장 {#var}

URI 프래그먼트(앵커)에 사용됩니다.

• 템플릿: {#var}
• 값: {"var": "section1"}
• 결과: #section1

4. 점(.)을 포함한 라벨 확장 {.var}

파일 확장자에 주로 사용됩니다.

• 템플릿: /config{.format}
• 값: {"format": "json"}
• 결과: /config.json

5. 경로 세그먼트 확장 {/var}

앞에 슬래시를 자동으로 추가합니다.

• 템플릿: {/var}
• 값: {"var": "user"}
• 결과: /user

6. 쿼리 매개변수 확장 {?var}

API 검색 및 필터링에 가장 많이 사용되는 유형입니다.

• 템플릿: /search{?q,lang}
• 값: {"q": "test", "lang": "en"}
• 결과: /search?q=test&lang=en

---

변수 수정자 (Modifiers)

URI 템플릿은 변수가 확장되는 방식을 제어하기 위한 수정자를 지원합니다.

• 분해 (*): 배열이나 객체에 사용됩니다.
  • 템플릿: /users{?id*}
  • 값: {"id": [1, 2, 3]}
  • 결과: /users?id=1&id=2&id=3
• 접두사 (:n): 처음 n개의 문자만 가져옵니다.
  • 템플릿: /{var:3}
  • 값: {"var": "abcdef"}
  • 결과: /abc

---

왜 URI 템플릿을 사용해야 하나요?

1. 디커플링(Decoupling): 클라이언트는 URL을 구성하는 방법을 알 필요가 없으며, 템플릿과 변수만 있으면 됩니다.
2. HATEOAS: 애플리케이션 상태의 엔진으로서의 하이퍼미디어(Hypermedia as the Engine of Application State)에 필수적입니다. 서버는 응답에 템플릿을 제공할 수 있습니다.
3. 일관성: 다양한 프로그래밍 언어와 라이브러리에서 쿼리 매개변수와 경로 세그먼트를 처리하는 표준화된 방법을 제공합니다.

---

자주 묻는 질문 FAQ

Q: {var}는 많은 라우터에서 사용되는 :var와 같은 것인가요? A: 개념적으로는 유사하지만, RFC 6570은 문서와 하이퍼미디어에서 이를 표현하는 방식에 대한 공식 표준입니다. 대부분의 라우터(Express 또는 React Router 등)는 단순화된 전용 구문을 사용합니다.

Q: 예약어 문자는 어떻게 처리하나요? A: 기본적으로 단순 확장 {var}는 예약어 문자를 퍼센트 인코딩합니다. 그대로 유지하려면 {+var}를 사용하세요.

Q: URI 템플릿은 대소문자를 구분하나요? A: 명세에 따르면 변수 이름은 대소문자를 구분합니다. {var}와 {VAR}는 서로 다른 변수입니다.

---

관련 도구

• URL 인코더/디코더 - 템플릿 확장 시 문자가 어떻게 인코딩되는지 확인하세요.
• JSON 포맷터 - 템플릿을 채우는 데 사용할 JSON 데이터를 정리하세요.
• 정규식 테스터 - URI 세그먼트 검증에 사용할 패턴을 테스트하세요.