API 변경 전에 합의해야 할 버전·폐기·호환 기준

API 변경 전에 팀이 먼저 합의해야 할 것은 버전 이름이 아니라 호환성의 의미와 폐기 시점입니다. 기존 클라이언트가 같은 요청을 보냈을 때 응답을 계속 해석할 수 있는지, 변경 사실을 언제 어떻게 알릴지, 전환이 끝났다고 판단할 근거가 무엇인지 문서로 고정해야 합니다. 이 세 가지가 없으면 v2를 추가해도 실제로는 예고 없이 계약을 깨는 운영이 됩니다.

실무에서는 변경을 호환 변경, 조건부 호환 변경, 비호환 변경으로 분류하고 각각 다른 절차를 적용하는 방식이 가장 안전합니다. 필드 추가처럼 소비자가 무시할 수 있는 변화라도 모든 클라이언트가 엄격한 스키마 검증을 하는지 확인해야 하며, 이름 변경·삭제·의미 변경은 새 계약과 유예 기간을 준비해야 합니다. 아래 기준을 변경 승인 템플릿과 배포 체크에 그대로 넣으면 판단을 사람의 기억에 의존하지 않게 됩니다.

호환성은 무엇을 기준으로 판정할까

호환성은 서버 구현이 아니라 공개 계약의 관점에서 판정합니다. 요청에서는 기존 필수 파라미터의 의미와 허용 값이 유지되는지, 응답에서는 기존 필드의 타입·null 가능성·단위·오류 형식이 유지되는지를 봅니다. 새 응답 필드를 추가하는 것은 대체로 안전하지만, 클라이언트가 알 수 없는 필드를 거부하는 생성 코드나 열거형을 사용한다면 예외가 됩니다. 문서의 예시만 비교하지 말고 실제 SDK, 모바일 앱, 배치 작업, 외부 파트너가 어떤 가정을 하는지 목록화해야 합니다.

• 필드 이름·타입·필수 여부·기본값·단위가 기존 의미와 같은가

• 오류 상태 코드와 오류 본문을 기존 소비자가 처리할 수 있는가

• 페이지네이션, 정렬, 시간대처럼 숨은 계약이 바뀌지 않았는가

• 엄격한 역직렬화·코드 생성·캐시가 새 값을 만났을 때 안전한가

버전 전략보다 먼저 정할 운영 경계

버전 위치는 URL, 헤더, 미디어 타입 중 하나를 선택할 수 있지만 팀이 지켜야 할 경계가 더 중요합니다. 한 버전 안에서는 비호환 변경을 금지하고, 호환 변경도 changelog와 계약 테스트를 함께 갱신한다는 규칙을 정합니다. 새 버전은 단순히 구현을 복사하는 일이 아니라 지원 범위, 인증 방식, 사용량 측정, 문서 주소, SDK 배포 대상을 함께 정의하는 릴리스 단위여야 합니다. 버전별 담당자와 지원 종료 책임자도 지정해야 장애 때 결정이 멈추지 않습니다.

특히 버전 숫자를 올리는 기준을 모호하게 두면 개발자는 작은 수정에도 새 버전을 만들고, 소비자는 버전이 많아질수록 전환을 미룹니다. 변경 영향이 계약을 깨는지부터 판단하고, 깨지지 않는다면 같은 버전에서 점진적으로 배포합니다. 반대로 응답 의미가 바뀌거나 보안상 허용할 수 없는 동작을 제거한다면 숫자보다 명확한 새 계약과 마이그레이션 문서가 우선입니다.

폐기 공지는 언제 시작해야 하는가

폐기는 삭제 배포일이 아니라 공지를 시작하는 순간부터 관리해야 합니다. 공지에는 대상 버전과 엔드포인트, 폐기 사유, 마지막 정상 사용일, 대체 계약, 전환 예시, 문의 창구를 포함합니다. 날짜만 적은 공지는 전환을 돕지 못하므로 호출량과 활성 클라이언트 목록을 확인할 수 있는 관측 기준도 함께 알려야 합니다. 법적·보안상 즉시 중단이 필요한 경우에는 일반 유예 절차의 예외 조건과 승인자를 기록합니다.

유예 기간은 모든 소비자가 동일하게 길 필요는 없습니다. 내부 서비스처럼 배포를 통제할 수 있는 대상과 고객이 직접 설치하는 앱은 전환 속도가 다릅니다. 따라서 최소 공통 기간을 정한 뒤, 실제 호출이 남아 있으면 연장할지, 특정 보안 취약점이면 단축할지 조건을 명시합니다. 폐기 헤더나 응답 경고를 제공하면 소비자가 로그에서 전환 신호를 확인할 수 있고, 대시보드에는 버전별 성공률·오류율·최근 호출 시각을 남길 수 있습니다.

마이그레이션 완료를 어떻게 증명할까

전환 완료는 새 버전이 배포됐다는 사실만으로 증명되지 않습니다. 구버전 호출량이 0에 가까워졌는지, 신규 계약의 핵심 시나리오가 계약 테스트와 실제 트래픽에서 통과하는지, 롤백 경로가 준비됐는지를 확인해야 합니다. 고객별 호출이 보이지 않는 구조라면 인증 주체·앱 버전·키 식별자를 보강하되 개인정보를 과도하게 수집하지 않도록 보존 기간과 접근 권한을 같이 정합니다. 마지막 호출 이후 관찰 기간이 지나야 삭제 승인으로 넘어갑니다.

1. 변경 diff를 계약 기준으로 분류하고 호환성 판정을 승인받는다.

2. 문서·예제·SDK·계약 테스트를 같은 릴리스에서 갱신한다.

3. 폐기 대상과 대체 경로, 날짜, 담당자를 공지하고 경고를 노출한다.

4. 호출량과 오류를 관찰해 전환 조건을 충족한 뒤 삭제를 승인한다.

변경 승인 체크리스트

승인자는 다음 질문에 예라고 답할 수 있어야 합니다. 영향받는 소비자와 담당자가 식별됐는가? 기존 요청·응답의 의미와 오류 계약을 비교했는가? 새 버전이 필요하다면 지원 종료와 대체 경로가 문서화됐는가? 공지와 유예 기간이 소비자 유형별로 현실적인가? 호출량·로그·계약 테스트로 완료를 증명할 수 있는가? 긴급 중단의 예외와 롤백 책임자가 정해졌는가? 하나라도 답하지 못하면 배포보다 계약 정리가 먼저입니다.

좋은 API 버전 관리는 숫자를 늘리는 기술이 아니라 변경의 책임을 분산시키지 않는 약속입니다. 팀은 호환성 분류, 폐기 공지, 관측 가능한 완료 조건을 한 문서 흐름으로 묶고 매 변경마다 같은 질문을 반복해야 합니다. 그렇게 해야 소비자가 안전하게 이동할 시간을 확보하면서도 오래된 계약을 끝내는 결정을 예측 가능하게 내릴 수 있습니다.