API 버저닝 전략 실전: URI vs Header vs Media Type, 언제 갈아타야 하는가

API 버저닝 전략 실전: URI vs Header vs Media Type, 언제 갈아타야 하는가

API 버저닝은 URL 취향 싸움이 아니라, 호환성 비용을 어떤 계층에서 감당할지 정하는 선택이다.

중급 팀에서는 신규 버전을 만드는 기준, 이전 버전 폐기 절차, 고객사 마이그레이션 가시성까지 포함해 설계해야 한다.

왜 지금 이 주제가 중요한가

• 버전 전략이 없으면 하위 호환성 부담이 코드 전체로 퍼진다.
• 버전이 많아질수록 운영/문서/모니터링 비용이 함께 증가한다.
• 중요한 것은 어디에 버전을 넣느냐보다 언제 breaking change로 판단하느냐이다.

핵심 설계 포인트

• URI 버저닝은 명시적이고 디버깅이 쉽지만 경로 중복이 커질 수 있다.
• Header 또는 media type 버저닝은 자원 식별을 유지하지만 클라이언트와 게이트웨이 지원을 점검해야 한다.
• breaking change 기준과 sunset timeline을 문서/헤더/공지 채널로 함께 관리한다.
• 버전별 트래픽을 관측할 수 있어야 실제 폐기가 가능하다.

예시 구성

GET /v2/orders/123
Accept: application/vnd.example.orders.v2+json
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Deprecation: true

적용 순서(실무 플로우)

설계 자체보다도 '작게 도입하고 관측하면서 확장하는 순서'가 운영 성공률을 좌우한다.

1. 지금까지 발생한 breaking change 사례를 모아 버전 정책 문장으로 정리한다.
2. 신규 버전 노출 방식(URI, header, media type)을 API 게이트웨이 제약과 함께 검토한다.
3. Deprecation/Sunset 헤더, 문서, 고객 공지 템플릿을 만든다.
4. 버전별 사용량 대시보드를 만들고, 지원 종료 기준을 운영 정책으로 박는다.
5. 핵심 SDK 또는 샘플 코드도 버전 전환 흐름에 맞춰 같이 업데이트한다.

운영 체크포인트

• 지원 종료 전 고객사별 버전 사용량을 확인할 수 있어야 한다.
• 새 버전 배포 전 SDK/문서/예제 코드가 함께 준비돼야 한다.
• 버전별 알람과 에러율을 분리해 회귀를 빠르게 잡는다.

운영 지표/알람 추천

• 버전별 트래픽 비율과 미지원 버전 접근 수
• deprecation/sunset 헤더 적용률
• 클라이언트 오류율(4xx)과 호환성 이슈 건수
• 변경 후 고객사별 migration 진행률

빠른 점검 명령/쿼리

curl -I https://example.com/api/resource
curl -H 'Accept: application/vnd.example.v2+json' https://example.com/api/resource
rg 'Sunset|Deprecation|api-version' ./logs -n

구조화 로그 필드 추천

• traceId/requestId/eventId처럼 흐름을 이어주는 키를 남긴다.
• endpoint/topic/flag/version 등 주제별 핵심 차원을 구조화한다.
• 실패 이유(reasonCode)와 재시도 횟수(retryAttempt)를 분리한다.
• 민감정보는 마스킹하고, payload는 샘플링 또는 요약 저장한다.

{
  "level": "INFO",
  "message": "request completed",
  "traceId": "4bf92f...",
  "requestId": "req_123",
  "path": "/api/example",
  "status": 200,
  "latencyMs": 123,
  "reasonCode": null
}

테스트 케이스 샘플

테스트 케이스(최소 3종):
1) 정상: 기대한 성공 경로와 상태 전이가 유지되는지
2) 실패: 다운스트림 오류/잘못된 입력이 예측 가능한 에러로 떨어지는지
3) 동시성/재시도: 같은 요청 또는 이벤트가 반복돼도 부작용이 없는지

추가(가능하면):
- 장애 복구: 프로세스 재시작 후 중간 상태를 정상 회복하는지
- 부하: p95/p99와 queue/pool saturation이 임계값 안에 드는지

트레이드오프/대안

• 운영 복잡도를 줄이면 기능 유연성이 떨어질 수 있고, 반대도 마찬가지다.
• 기본값은 출발점일 뿐이다. 실제 트래픽과 실패 패턴을 보고 다시 조정해야 한다.
• 관측 없이 최적화하면 체감 개선과 회귀를 구분하기 어렵다.
• 팀 경계가 많은 시스템일수록 인터페이스 계약과 문서가 코드만큼 중요하다.

성공 기준(SLO) 예시

• 핵심 경로 에러율: 0.1% 이하
• 핵심 요청/이벤트 p95 지연: 서비스 목표 내 유지
• 중복 실행 또는 데이터 유실: 0건
• 장애 감지 후 임시 조치까지 걸리는 시간: 10분 이내

자주 터지는 실수/트러블슈팅

1. 버전은 URL에만 있고 정책이 없다: 결국 아무 버전도 지우지 못한다.
2. 사소한 변경까지 버전을 올린다: 문서와 운영 비용만 커진다.
3. Sunset 공지 없이 구버전을 끊는다: 고객 장애가 곧 신뢰 하락으로 이어진다.

바로 적용 템플릿

버전 정책 템플릿:
breaking change 정의
노출 방식(URI/header/media type)
Deprecation / Sunset 공지 절차
버전별 트래픽 모니터링

검증 방법

• 구버전과 신버전 클라이언트가 같은 배포에서 동시에 동작하는지 통합 테스트한다.
• 지원 종료 헤더와 문서 링크가 실제 응답에 포함되는지 확인한다.

장애 대응 Runbook(초안)

• 현상: 어떤 사용자/서비스/플랫폼에서 무엇이 깨졌는지 한 문장으로 정리한다.
• 범위: 언제부터 시작됐고, 영향받은 비율과 핵심 경로를 적는다.
• 증거: 로그 3줄, 지표 1개, 최근 배포/설정 변경 1개를 먼저 모은다.
• 임시 조치: 차단, 롤백, 스위치 전환, 재시도 제한 중 무엇을 할지 결정한다.
• 근본 원인: 계약, 타임아웃, 락, 캐시, 버전, 운영 절차 중 어디가 깨졌는지 좁힌다.
• 재발 방지: 테스트, 알람, 문서, 기본값을 함께 수정한다.

리뷰 체크리스트

1. 실패 시나리오가 문서와 코드에서 같은 의미로 정의돼 있다.
2. 타임아웃/재시도/락/캐시 같은 보호 장치가 상호 충돌하지 않는다.
3. 관측 지표와 상관관계 키가 있어 운영 중 재현이 가능하다.
4. 롤백 또는 비상 스위치가 준비돼 있다.
5. 최소 1개 이상의 동시성/부하/중간 실패 테스트가 자동화돼 있다.
6. 공식 문서 링크와 팀 의사결정 근거가 남아 있다.

팀 문서 템플릿

팀 문서 템플릿(복붙용):
1) 목표/배경: 어떤 운영 비용 또는 장애를 줄이려는가
2) 범위: API/잡/토픽/디바이스/리전 중 어디까지 적용하는가
3) 규칙: 키, 상태, 버전, TTL, timeout, retry 기본값
4) 예외: 허용하지 않는 상황과 에러 코드/조치 기준
5) 운영: 대시보드, 알람, 소유 팀, 점검 주기
6) 장애 대응: 임시 조치, 롤백, 후속 공지 절차
7) 변경 이력: 언제 누가 왜 기본값을 바꿨는가

FAQ(자주 묻는 질문)

Q. 처음부터 완벽하게 설계해야 하나요?
A. 아니다. 핵심 경로 1개부터 적용하고, 운영 지표를 보며 기본값을 보정하는 편이 실제로 더 안전하다.

Q. "API 버저닝 전략 실전: URI vs Header vs Media Type, 언제 갈아타야 하는가"를 도입했는데도 문제가 남아 있습니다. 어디부터 봐야 하나요?
A. 먼저 상관관계 키가 있는 로그와 지표로 실패 범위를 좁히고, 최근 배포/설정 차이를 확인한다. 대부분은 기본값보다 경계 조건에서 터진다.

Q. 팀 합의가 자꾸 흔들립니다. 무엇을 문서로 남겨야 하나요?
A. 상태 전이, 기본값, 예외 처리, 롤백 기준 네 가지는 반드시 남겨야 한다. 이 네 가지가 없으면 장애 때 판단이 흔들린다.

참고/출처

• RFC 9110: HTTP Semantics
• GitHub REST API Versioning