API 종료 날짜를 알리는 데서 끝내지 않고 실제 사용 고객을 찾아 전환·검증하는 절차를 정리합니다.
왜 이 문제가 생길까
구버전 API를 유지하면 유지보수 비용이 늘지만 갑자기 끄면 고객 연동이 멈춥니다. 문서에 종료 날짜를 써 두어도 실제 호출 주체가 누구인지 모르면 공지는 닿지 않습니다. 호출량이 0이라는 사실도 오래된 배치가 월말에만 도는 경우에는 충분한 증거가 아닙니다.
시스템은 무엇을 구분해야 할까
엔드포인트별 호출 주체, 마지막 호출 시각, 호출 주기, 응답 오류를 기록하되 개인 데이터는 최소화합니다. 공지에는 대체 API, 기능 차이, 마이그레이션 가이드, 테스트 환경, 종료 예정일을 함께 제시합니다. 가능한 경우 표준 Deprecation·Sunset 헤더로 기계가 읽을 수 있는 신호도 제공합니다. 구버전과 신버전을 일정 기간 병행하며 응답 의미와 권한 범위가 같은지 비교합니다.
현장에서 적용하면
평소 호출이 없는 ERP 연동이 매월 마지막 영업일에 작동한다면 일주일의 무호출 관찰만으로 종료하면 안 됩니다. 담당자에게 사용 사실을 알려 테스트 호출을 요청하고, 전환 여부를 실제 요청 로그로 확인합니다. 오류가 발생할 때는 고객별 구버전 잔존 비율과 실패율을 함께 보면서 종료일 연기 여부를 결정합니다.
도입할 때 놓치기 쉬운 점
버전만 올리고 의미가 바뀐 필드를 숨기면 고객은 정상 응답을 받아도 업무 오류를 겪습니다. 공지 이메일 발송 수를 완료율로 보지 말고 활성 호출 주체의 전환율을 추적해야 합니다. 더는 안전하지 않은 API라면 긴 유예가 항상 답은 아니므로 위험도에 맞는 예외 정책을 별도로 설명해야 합니다.
시작 전 점검할 세 가지
- 구버전 호출 주체와 호출 주기를 파악했는가
- 대체 API의 의미 차이와 테스트 경로를 제공했는가
- 종료 판단에 실제 전환 사용량을 반영하는가
참고 자료: IETF RFC 9745 Deprecation 헤더
#API #API버전관리 #Deprecation #Sunset #마이그레이션 #고객연동 #백엔드설계 #서비스운영 #개발자경험 #호환성
