모바일 앱과 파트너용 API 발전시키기: 버전, 호환성, 종료
핵심 요약: 웹사이트는 언제든 업데이트할 수 있지만, 사용자 휴대폰에 설치된 앱과 파트너의 시스템은 그렇지 않습니다. API를 한 번 내놓으면 호출자가 오랫동안 업그레이드하지 않는다고 가정해야 합니다. 우리의 규칙은 이렇습니다. 호환되는 변경은 기존 버전에 넣고, 호환되지 않는 변경은 새 버전으로 냅니다. 옛 버전은 지원 중단으로 표시하고 호출자별 사용량을 측정합니다. 사용량이 허락할 때 종료합니다. 계약은 파일로 두고 CI가 검사합니다.
1.0 무엇이 호환되는가
| 변경 | 호환 여부 |
|---|---|
| 선택 요청 필드 추가, 응답 필드 추가 | 호환. 단, 클라이언트가 모르는 필드를 무시해야 함 |
| 엔드포인트 추가 | 호환 |
| 필드 삭제·이름 변경, 타입 변경 | 비호환 |
| 선택 필드를 필수로 변경 | 비호환 |
| 열거값 추가 | 클라이언트가 모르는 값을 어떻게 처리하느냐에 달림. 비호환으로 평가하는 편이 안전 |
| 오류 코드나 기본 정렬 변경 | 흔히 호환으로 취급되지만 이에 기대는 클라이언트를 깨뜨림 |
사고가 많이 나는 곳은 마지막 두 줄입니다. 우리는 첫 버전부터 클라이언트 가이드라인에 모르는 열거값이 오면 충돌하지 말고 대체 표시를 하도록 적어 둡니다.
2.0 버전은 어디에 두는가
/v1/ 같은 경로에 두는 것이 가장 잘 보이고 로그, 게이트웨이 라우팅, 캐시와도 잘 맞아서 우리의 기본값입니다. 헤더에 두면 깔끔해 보이지만 디버깅 중에 놓치기 쉽습니다. 어디에 두든 버전은 비호환 변경이 있을 때만 올리고, 제품 버전 번호를 따라가지 않습니다.
같은 메이저 버전 안에서도 클라이언트 릴리스마다 작은 동작 차이가 필요할 때가 있습니다. 클라이언트가 헤더로 앱 버전을 보내게 하고 서버에서 판단하면, 작은 API 버전을 줄줄이 만드는 것보다 훨씬 다루기 쉽습니다.
3.0 계약은 파일이다
API는 OpenAPI 같은 기술 파일로 정의해 저장소에 둡니다. CI는 두 가지를 합니다. 변경 사항을 직전 릴리스의 계약과 비교해 새 버전에 들어 있지 않은 비호환 변경이 있으면 빌드를 실패시키고, 계약 테스트로 구현이 기술과 일치하는지 확인합니다.
파트너용 API에서는 계약 파일이 개발자 매뉴얼의 원천이 되며, 별도 문서를 따로 관리하지 않습니다. 따로 쓴 두 문서는 언젠가 어긋납니다.
4.0 지원 중단과 종료
- 새 버전을 낼 때 옛 버전의 응답에 Deprecation과 Sunset 헤더(RFC 9745, RFC 8594)를 붙이고, 문서에 종료일을 적습니다.
- 옛 버전 사용량을 호출자별로 측정합니다. 어떤 앱 버전, 어떤 파트너 키가 아직 호출하는지입니다.
- 모바일에는 최소 지원 버전을 둡니다. 서버가 최소 버전을 내려 주고, 그보다 오래된 앱은 업데이트를 안내합니다.
- 사용량이 받아들일 만한 수준으로 내려간 뒤에 종료합니다. 종료 후에는 맥락 없는 404가 아니라 명확한 오류 코드와 업데이트 안내를 돌려줍니다.
종료일은 앱 스토어 심사와 사용자의 업데이트 속도를 고려해 정하고, 파트너에게는 자체 개발, 테스트, 배포에 필요한 시간을 줍니다.
5.0 멱등성과 재시도
모바일 네트워크에서는 재시도가 일상입니다. 생성 계열 엔드포인트는 멱등 키를 받습니다. 클라이언트가 작업마다 키를 만들고, 서버는 일정 기간 같은 키에 같은 결과를 돌려줍니다. “주문이 두 번 제출됐다” 같은 문제를 프로토콜 단계에서 막을 수 있습니다.
앱이나 파트너용 API를 설계하거나 통제를 벗어난 API를 정리하려면 웹·클라우드·디바이스 관리를 참고하거나 프로젝트 상담으로 연락 주세요.
참고 자료
- RFC 9745, The Deprecation HTTP Response Header Field: https://www.rfc-editor.org/rfc/rfc9745
- RFC 8594, The Sunset HTTP Header Field: https://www.rfc-editor.org/rfc/rfc8594
- OpenAPI Specification: https://spec.openapis.org/oas/latest.html
자주 묻는 질문
우리 웹 프런트엔드만 쓰는 엔드포인트도 이렇게 엄격해야 하나요?
백엔드와 함께 배포하고 함께 롤백하는 웹 프런트엔드라면 계약 검사만 계속 돌리면서 느슨하게 다뤄도 됩니다. 모바일 앱, 미니 프로그램, 외부 시스템처럼 서버와 보조를 맞춰 배포할 수 없는 클라이언트가 하나라도 있으면 이 글의 규칙을 따릅니다.
GraphQL을 쓰면 버전 관리가 필요 없나요?
GraphQL은 버전을 나누지 않고 필드 추가와 지원 중단 표시로 발전시키는 것이 관례인데, 본질은 같은 호환성 규율입니다. 필드를 삭제하기 전에 누가 아직 그것을 조회하는지 알아야 한다는 점도 같습니다.
옛 버전은 얼마나 유지해야 하나요?
일반적인 답은 없고, 사용자의 업그레이드 속도와 파트너의 배포 주기에 달려 있습니다. 우리는 실제 사용량으로 결정하고, 새 버전을 낼 때 종료일을 미리 공지해 호출자가 계획에 넣을 수 있게 합니다.
내부를 리팩터링했습니다. 공개 API도 바꿔야 하나요?
API는 외부에 대한 약속이지 내부 구조를 비추는 것이 아닙니다. 서버에서 매핑해 외부 계약을 그대로 두는 것이 내부 리팩터링에서는 대개 가장 저렴한 방법입니다.