API를 개선하려고 응답 필드를 바꿨는데, 모바일 앱 구버전이나 외부 파트너 연동이 깨지는 순간 운영 리스크가 커집니다. 이 글에서는 Node.js 백엔드 기준으로 API 버전 관리와 하위 호환성 유지 방법을 실무 관점에서 정리합니다.

왜 API 버전 관리가 필요한가

클라이언트 업데이트 속도는 서버보다 느리다

서버는 오늘 배포해도, 사용자의 앱은 며칠~몇 주 뒤에 업데이트될 수 있습니다. 즉, 같은 시점에 서로 다른 API 기대값을 가진 클라이언트가 공존합니다.

파트너/외부 연동은 즉시 변경이 어렵다

B2B 연동, 사내 타 시스템, 자동화 스크립트는 변경 주기가 더 깁니다. 서버에서 응답 구조를 급격히 바꾸면 장애 전파 범위가 커집니다.

Node.js API 버전 전략 선택

URL 버전 방식: /v1, /v2

가장 명확하고 운영이 쉬운 방식입니다. 라우팅, 모니터링, 문서 분리가 직관적이라 팀 온보딩에도 유리합니다.

import express from 'express';
const app = express();

app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

헤더 버전 방식: Accept 또는 커스텀 헤더

URI를 깔끔하게 유지할 수 있지만, 클라이언트/프록시/테스트 환경에서 헤더 관리가 복잡해질 수 있습니다.

app.use((req, _res, next) => {
  req.apiVersion = req.get('X-API-Version') ?? '2026-01-01';
  next();
});

실무 권장: “큰 변경은 URL 버전, 작은 변경은 확장형 필드”

  • Breaking change(필드 제거, 타입 변경): 새 메이저 버전(/v2)
  • Non-breaking change(필드 추가): 기존 버전에 선택적 필드 확장

하위 호환성을 지키는 변경 원칙

1) 필드 제거보다 “Deprecated → 유예 → 제거”

즉시 삭제하지 말고, 제거 예정 공지와 유예 기간을 둡니다. 응답/문서/로그에 deprecation 신호를 같이 남기세요.

res.setHeader('Deprecation', 'true');
res.setHeader('Sunset', 'Wed, 30 Sep 2026 00:00:00 GMT');

2) 타입 변경은 새 필드 추가로 우회

amount: string을 number로 바꾸고 싶다면 기존 필드를 유지한 채, amountValue 같은 새 필드를 추가하고 점진 전환합니다.

3) 기본값과 null 정책을 문서화

클라이언트는 null, 빈 문자열, 필드 미존재를 다르게 처리합니다. 버전별 응답 계약(contract)을 명확히 문서화해야 회귀를 줄일 수 있습니다.

안전한 롤아웃 순서 (실무 템플릿)

1단계: 신규 버전 배포 (구버전 유지)

  • /v2 라우트를 추가하되 /v1을 유지
  • 모니터링 대시보드에서 v1/v2를 분리 관찰

2단계: 트래픽 점진 전환

  • 내부 클라이언트 → 일부 파트너 → 전체 순으로 이전
  • 에러율, p95 지연, 4xx 패턴 변화 추적

3단계: Deprecation 공지 및 마이그레이션 가이드 배포

  • 제거 일정 공지
  • 코드 예제와 체크리스트 제공
  • 문의 채널(슬랙/메일) 명시

4단계: 사용량 기반 종료

  • v1 호출 비율이 임계치 이하일 때 종료
  • 종료 직전 재공지 + 완충 기간 제공

운영 체크리스트

배포 전

  • 버전별 OpenAPI 문서 분리
  • 계약 테스트(contract test) 자동화
  • 주요 클라이언트 호환성 확인

배포 중

  • 버전별 에러율/지연 모니터링
  • 타임아웃, 재시도, 서킷 브레이커 설정 점검
  • 민감정보가 로그에 남지 않도록 마스킹

배포 후

  • v1 잔여 트래픽 식별 및 개별 커뮤니케이션
  • 제거 일정 재확인
  • 회고 작성(다음 버전 정책 템플릿화)

요약

API 버전 관리의 핵심은 “새 버전을 빨리 만드는 것”보다 기존 사용자를 깨지 않게 천천히 옮기는 운영 설계입니다. Node.js 환경에서는 라우팅 분리, 계약 테스트, deprecation 정책만 잘 갖춰도 대부분의 하위 호환성 사고를 예방할 수 있습니다.

내부 링크