URI vs Header vs Query 방식 비교와 실무 가이드
1️⃣ API 버전 관리가 왜 중요한가?
API는 시간이 지나며 점점 확장되고 진화합니다.
- 요청 파라미터 구조 변경
- 응답 필드 추가 또는 제거
- 인증 방식 변경
- 비즈니스 로직 변경
이러한 변화에 대응하기 위해 API 버전 관리 전략은 필수입니다.
2️⃣ 주요 API 버전 관리 방식 3가지
✅ ① URI 방식
GET /api/v1/products- 가장 흔하고 직관적인 방식
- Swagger/OpenAPI 문서와 잘 호환됨
장점
- 명확한 구조
- 문서화, 테스트에 유리
- API Gateway, CDN 캐싱에 적합
단점
- RESTful 관점에서는 리소스 이름이 바뀐 것으로 간주될 수 있음
- 경로가 복잡해질 수 있음
✅ ② HTTP Header 방식
GET /api/products
Accept: application/vnd.myapi.v1+json
- HTTP Header에 버전 정보를 포함
- URI는 고정, 버전은 헤더로 분기
장점
- REST 리소스 개념 유지
- 경로가 깔끔함
단점
- 테스트/디버깅 어려움
- Swagger 문서화가 번거로움
- 프록시, CORS 설정이 복잡해질 수 있음
✅ ③ Query Parameter 방식
GET /api/products?version=1장점
- 빠르고 간단
- 동적 라우팅 및 테스트 환경에서 유용
단점
- RESTful하지 않음
- 문서화 시 불리
- 캐싱 전략 수립이 어려움
3️⃣ 실무 기준 비교 표
| 기준 | URI 방식 | Header 방식 | Query 방식 |
|---|---|---|---|
| 직관성 | ✅ 높음 | ❌ 낮음 | 🔸 보통 |
| 문서화 호환성 | ✅ Swagger 호환 | ❌ 별도 처리 필요 | 🔸 가능 |
| REST 원칙 | 🔸 일부 충돌 | ✅ 적합 | ❌ 위반 |
| 테스트/디버깅 편의 | ✅ 쉬움 | ❌ 불편 | ✅ 쉬움 |
| API Gateway 설정 | ✅ 단순 | 🔸 헤더 파싱 필요 | ✅ 단순 |
| 운영 유지 보수 | ✅ 안정적 | 🔸 숙련도 필요 | ❌ 불안정 |
4️⃣ 실무 적용 전략
- 외부 공개 API: URI 방식 권장
- 사내 서비스 API: Header 방식 추천
- PoC / 임시 테스트: Query 방식도 가능
5️⃣ 버전 관리 시 주의할 점
- 응답 필드만 바뀌어도 버전 분리 필요
- 버전별 API 명세서 분리
- Deprecated 정책 수립 필수
- 기존 버전은 일정 기간 유지
6️⃣ 마무리 + 추천 전략
| 상황 | 추천 방식 |
|---|---|
| 외부 공개 API | URI 방식 |
| 사내 서비스 API | Header 방식 |
| PoC/테스트 용도 | Query 방식 |
🔗 참고자료
'IT' 카테고리의 다른 글
| 웹 보안 기초 – CSRF vs XSS 완전정복 (0) | 2025.04.17 |
|---|---|
| API 명세서, 어떻게 작성하고 관리해야 할까? (0) | 2025.04.10 |
| CORS 완벽 정리 + 실전 해결 방법 (0) | 2025.04.03 |
| HTTP 상태코드 실무 정리 & 상황별 추천 (0) | 2025.04.02 |
| 개발자들이 자주 헷갈리는 REST API 설계 총정리 (실전편) (0) | 2025.03.31 |