API 마이그레이션 가이드는 어떻게 작성하는가

API 마이그레이션 가이드란 호환되지 않는 변경을 장애가 아니라 체크리스트로 바꾸는 문서다. 무엇이 바뀌었는지, 그것에 대해 무엇을 해야 하는지, 그리고 언제까지인지. 체인지로그 항목은 호환되지 않는 변경을 두 문장으로 이름 붙일 수 있지만, 마이그레이션 가이드는 그 두 문장이 “이건 당신을 깨뜨린다”고 말할 때 호출자가 실제로 열어보는 것이며, 정확히 무엇을 수정해야 하는지 알아야 하는 순간이다. 가이드 없이 항목을 게시하는 것은 호출자가 그것을 막기 위해 쓰인 문서 대신 지원 티켓을 통해 호환되지 않는 변경을 알게 되는 방식이다.

API 마이그레이션 가이드란 무엇인가

호출자를 API의 예전 형태에서 새 형태로 데려가는 단계별 문서로, API를 채택할지 아직 결정 중인 사람이 아니라 수정할 코드가 있는 사람을 위해 작성된다. 이 구분은 중요하다. 마이그레이션 가이드는 기존 통합과 기존 프로덕션 트래픽을 전제로 하므로 롤백, 부분 마이그레이션, 마이그레이션이 성공했는지 아는 방법을 다뤄야 하는데, 첫 통합을 위한 가이드는 이 중 어느 것도 다룰 필요가 없다.

마이그레이션 가이드는 보통 마지막 두 개 사이에 위치한다. 비추천 공지는 시계를 시작시키고, 마이그레이션 가이드는 그 시계가 다 되기 전에 호출자가 따르는 것이다.

변경이 체인지로그 항목만이 아니라 마이그레이션 가이드가 필요한 때는 언제인가

예전 동작과 새 동작 사이에 한 단계 이상이 있을 때, 또는 변경이 충분히 많은 호출 지점을 건드려서 호출자가 설명보다 실제로 작성된 예시에서 더 이익을 얻을 때다. 호환되지 않는 변경이란 무엇이고 어떻게 출시하는가가 변경이 호환되지 않는지 판단하는 테스트를 다룬다. 답이 그렇다면, 두 번째 질문은 수정이 한 줄짜리 편집인지 진짜 마이그레이션인지다. 이름이 바뀐 필드는 호출자가 체인지로그 항목만으로 처리할 수 있다. 인증, 페이지네이션, 오류 처리의 변경은 거의 항상 가이드를 받을 자격이 있는데, 올바른 대체 코드가 한 문장짜리 설명에서는 명확하지 않기 때문이다.

마이그레이션 가이드는 무엇을 담아야 하는가

다섯 가지이며, 그중 어느 하나라도 건너뛰는 것이 가이드를 호출자가 한 번 읽고 그다음에는 시행착오로 돌아가는 페이지로 만드는 방식이다. 예전 코드를, 실제 프로젝트에서 나타날 그대로 보여준다. 새 코드를, 같은 방식으로 보여준다, 차이에 대한 추상적인 설명이 아니라. 아무것도 바꾸지 않으면 무엇이 깨지는지 명확히 말한다, “아무것도”는 유효하고 흔한 답이지만 호출자는 그래도 그것을 명시적으로 들어야 하기 때문이다. 마이그레이션이 작동했는지 확인하는 방법, 확인할 응답 필드나 상태 코드 같은 것. 그리고 일정. 예전 동작이 언제 작동을 멈추는지, 그 사이에 두 형태가 모두 사용 가능한지.

## 통화 필드를 float에서 integer로 마이그레이션 (v3.0.0)

이전:
  { "amount": 19.99 }

이후:
  { "amount": 1999 }  // 가장 작은 통화 단위(센트)

무엇이 바뀌는가: `amount`는 이제 계정 통화의 가장 작은 단위의
정수다. `amount`를 float으로 읽는 코드는 2026년 10월 1일부터
100배 큰 값을 읽게 된다.

검증: 마이그레이션 후 19.99달러 청구는 `amount: 19.99`가 아니라
`amount: 1999`로 읽혀야 한다.

일정: v2는 2027년 1월 15일까지 계속 float를 반환한다. v3는 출시
시점부터 정수를 반환한다. 두 버전 모두 지금 활성 상태다.

이 다섯 가지 각각은 그렇지 않으면 호출자가 추측하거나 지원팀에 물어봐야 할 질문에 답하며, 그것이 바로 마이그레이션 가이드가 실제로 절약하는 비용이다.

누가 그것을 써야 하고, 언제 써야 하는가

변경을 설계한 사람이, 그것이 출시되는 바로 그 순간에. 일주일 후 티켓에서 그것을 재구성하는 지원팀이 아니다. 결정을 내린 사람은 예전 동작의 어느 부분에 아무도 의존하지 말았어야 했는지, 어느 부분이 우연한 계약이었는지 안다. 그 맥락 없이 나중에 누군가 쓴 가이드는 명백한 것을 과도하게 설명하거나 사람들을 실제로 망가뜨리는 그 하나의 엣지 케이스를 놓치는 경향이 있다. 가이드와 호환되지 않는 변경을 발표하는 체인지로그 항목은 함께 나와야 하며, 항목은 그것을 반복하는 대신 가이드로 링크해야 한다.

이것이 버전 관리 및 API 체인지로그와 어떻게 연결되는가

직접적으로. 마이그레이션 가이드는 시맨틱 버저닝과 당신의 체인지로그에서 MAJOR 항목이 한 문장으로만 요약하는 것의 상세 버전이다. 체인지로그 항목은 변경이 호환되지 않는다는 것과 대략 무엇이 바뀌었는지 말한다. 마이그레이션 가이드는 그 항목이 담아야 할 링크다. API 체인지로그: 무엇을 공개하고 누가 읽는가는 마이그레이션 가이드를 API가 유지하는 다섯 문서 중 하나로 나열하며, 각각 다른 질문에 답한다. 이것은 “A에서 B로 실제로 어떻게 옮기는가”에 답하는 것이며, 그 답이 보통 체인지로그 항목에는 너무 길기 때문에 정확히 자신만의 페이지를 받을 자격이 있다.

마이그레이션 가이드는 얼마나 오래 게시된 상태로 남아 있어야 하는가

최소한 예전 동작이 도달 가능한 동안은, 그리고 이상적으로는 그 이후에도. 세 번의 비추천 공지를 무시한 후 열여덟 달 늦게 마이그레이션하는 호출자도 여전히 가이드가 필요하며, 예전 동작이 꺼지는 그날 그것을 삭제하는 것은 그것이 가장 필요한 호출자가 그것을 찾지 못하도록 보장할 뿐이다. 안정적인 URL에 유지하고 페이지를 철회하는 대신 일정 섹션을 업데이트하라. Stripe 자체의 업그레이드 가이드가 바로 이 패턴의 공개된 사례다. 릴리스마다 새 문서를 만들어 다음 버전이 나오는 순간 낡아버리게 두는 대신, 페이지 하나를 계속 최신 상태로 유지한다. 여러분의 가이드도 블로그 아카이브에 묻혀 있지 말고, 호출자가 이미 읽고 있는 문서 바로 옆처럼 그만큼 찾기 쉬운 곳에 있어야 한다.

FAQ

모든 호환되지 않는 변경에 마이그레이션 가이드가 필요한가? 아니다. 호출자가 체인지로그 항목만으로 해결할 수 있는 변경, 예를 들어 명백한 대체가 있는 이름이 바뀐 필드 하나는 별도의 가이드가 필요 없다. 여러 호출 지점을 건드리거나 작성된 예시가 필요한 변경은 필요하다.

마이그레이션 가이드는 API 문서와 함께 있어야 하는가, 아니면 체인지로그에 있어야 하는가? 문서와 함께, 체인지로그 항목에서 링크되어야 한다. 항목은 구독자가 먼저 보는 것이고, 가이드는 행동하기로 결정한 순간 필요한 것이며, 호출자가 이미 사용하고 있는 참조 자료 옆에 속한다.

마이그레이션 가이드와 비추천 공지의 차이는 무엇인가? 비추천 공지는 무언가가 사라질 것이고 언제까지인지를 선언한다. 마이그레이션 가이드는 그것에 대해 무엇을 할지에 대한 지침이다. 링크된 마이그레이션 가이드가 없는 비추천 공지는 호출자에게 마감일은 주지만 그것을 어떻게 맞출지는 알려주지 않는다.

마이그레이션 기간 동안 예전 동작과 새 동작을 모두 문서화해야 하는가? 그렇다, 가능하다면 같은 페이지에. 호출자가 서로 다른 시기에 작성된 두 개의 별도 문서에서 조합하는 대신 정확히 무엇이 바뀌었는지 보게 하기 위해서다.

이 글의 기술적 내용은 독립적으로 검토되지 않았습니다. 잘못된 부분이 있으면 알려 주세요. 바로잡겠습니다.

changeloop 관련 페이지: 개발자 문서, changelog 예시