내부용 API 체인지로그: 다른 팀에게 무엇이 달라지는가

이 허브의 다른 모든 글은 API를 호출하는 쪽이 회사 밖에 있다고 가정한다. 고객사의 엔지니어, 파트너사, 문서를 스스로 찾아낸 누군가. 하지만 많은 API에는 완전히 다른 종류의 호출자가 있다. 복도 건너편이나 두 층 떨어진 곳에 있는 팀이다. 그리고 이것은 체인지로그가 그들에게 무엇을 빚지고 있는지에 대한 계산을 바꾸는데, 슬랙 메시지 하나면 그들에게 닿기 때문이고 서포트 티켓은 보통 아예 열리지 않기 때문이다. 대부분의 팀은 여기서 내부용 API는 체인지로그가 필요 없다는 결론을 내린다. 실제로 필요한 것은 다른 종류의 체인지로그다.

내부용 API의 체인지로그를 공개용과 다르게 만드는 것은 무엇인가

독자에게 직접 다가갈 수 있다는 점이며, 이것은 대부분의 공개 API 체인지로그가 존재하는 주된 이유, 즉 개별적으로 연락할 수 없는 호출자들에게 방송하는 이유를 없애버린다. 내부용 API를 소유한 팀은 보통 어떤 다른 팀이 그것을 호출하는지, 때로는 구체적인 서비스 단위까지 정확히 알고 있다. 이것은 공개 피드가 아니라 표적화된 메시지를 자연스러운 기본값으로 만들고, 그래서 내부용 API가 그토록 자주 체인지로그 없이 끝나는 이유이기도 하다. 소유 팀은 기억하고 있는 두세 팀에게만 알리고, 그것으로 모두를 다뤘다고 가정한다.

왜 “우리를 호출하는 팀들에게만 알리면 된다”는 무너지는가

호출자 집합이 소유 팀이 기억하는 것만큼 작거나 정적인 적이 없기 때문이다. 한 소비자를 위해 만들어진 서비스는 여섯 달 뒤, 아무도 발표하지 않은 통합을 통해 두 번째 호출자를 얻고, 소유 팀 머릿속의 “누가 우리를 호출하는가” 목록은 이제 틀렸는데도 아무도 그것을 알아채지 못한다. 이 실패는 흔하고 평범하다. 기록 대신 기억에 의존한 결과일 뿐, 누군가 부주의했다는 신호가 아니다. 브레이킹 체인지란 무엇인가는 애초에 API 변경이 브레이킹으로 간주되는지 어떻게 결정하는지를 다룬다. 내부용의 경우는 그 위에 누구에게 알려야 하는지 아는 것이라는 더 어려운 두 번째 질문을 얹는다.

내부용 API도 공개용 스타일의 체인지로그 페이지가 필요한가

주요 채널이 직접적이라 해도 보통은 필요하다. 페이지가 있으면 직접 보내는 메시지가 참조할 대상이 생기므로, 알림을 짧게 유지할 수 있다(“/v2/accounts에 브레이킹 체인지, 자세한 내용은 여기”) 스크롤되어 사라질 채팅 메시지에 전체 설명을 담으려 애쓰는 대신 말이다. 그것은 또한 새로운 팀이나 직접 메시지를 놓친 팀이, 통합이 깨졌을 때 왜 그런지 알아내려 할 때 확인할 수 있는 곳이 된다. 페이지가 세련되거나 공개될 필요는 없다. 링크할 수 있어야 하고 그것을 알린 슬랙 스레드보다 오래 살아남아야 할 뿐이다.

실제로 호출자 목록을 관리하는 것은 누구인가

소유 팀이며, 이것은 구전 지식이 아니라 실제 산출물로 다뤄져야 한다. 가장 저렴한 버전은 API 자체 저장소 안의 파일로, 새 통합이 만들어질 때마다 갱신되는 소비 서비스들의 짧은 목록에 항목마다 담당자를 붙인 것이다. 이것은 어떤 의존성 선언과도 같은 규율이다. 매번 브레이킹 체인지 전에 여기저기 물어보는 대안은 누군가가 올바른 사람에게 묻는 것을 잊는 그 한 번의 순간까지는 작동한다. 한 팀을 위해 조용히 깨지는 내부용 API는 공개용보다는 작은 사고지만, 여전히 사고이며, 보통은 API 소유자가 아니라 그 팀 자체의 온콜이 발견한다.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

이런 파일은 “누구에게 알려야 하는가”를 질문에서 조회로 바꾼다. 바로 이 문제를 위해 만들어진 도구들, 예를 들어 Backstage의 서비스 카탈로그는 같은 이유로 API를 선언된 소비자를 가진 일급 엔터티로 모델링한다. 조직이 내부 서비스를 충분히 많이 갖게 되면 누가 무엇을 호출하는지에 대한 기억은 저절로 정확하게 유지되지 않으며, 대신 그 기록을 보관할 무언가가 있어야 한다. 이미 사내에서 쓰고 있는 도구의 문서를 먼저 확인하는 것이 자체 제작에 나서기 전에 보통 옳은 순서다.

공개용에는 필요 없을 내부용 체인지로그 항목에 속하는 것은 무엇인가

더 많은 운영상의 구체성이다. 독자는 같은 인프라 안에서 이것을 근거로 행동할 또 다른 엔지니어이지, 이것을 요약으로 읽지 않기 때문이다. 변경이 어느 환경에서 언제 라이브되는지, 내부용 서비스는 공개 호출자가 결코 보지 못하는 단계들을 거쳐 승격되는 경우가 많기 때문이다. 변경이 소비 측에서 설정이나 클라이언트 라이브러리 업데이트를 요구하는지, 있다면 명령어로 표현된 형태로. 그리고 내부 호출자는 종종 소유 팀과 직접 수정을 조율할 수 있기 때문에, 서포트 채널 대신 이름이 명시된 담당자를 넣는다. “이게 뭔가 망가뜨리면 @maria에게 알려주세요”는 내부용 항목에서는 완전히 합리적인 한 줄이고 공개 API 체인지로그에서는 이상한 한 줄이다.

이것은 모노레포 안의 체인지로그에도 똑같이 적용되는가

이것은 문제를 대체하는 대신 같은 문제를 날카롭게 만든다. 모노레포 체인지로그는 패키지가 언제 자기만의 체인지로그가 필요한지 다룬다. 모노레포 안의 여러 패키지 중 하나인 내부용 API도 소비자가 명시적으로 추적되어야 한다는 점은 여전한데, 호출자와 같은 저장소를 공유한다고 해서 무언가가 보라고 알려주지 않는 한 그들이 변경을 알아챌 것이라는 뜻은 아니기 때문이다. 저장소 안에서의 가까움은 주의를 기울이는 것에서의 가까움과 같지 않다.

FAQ

순수하게 내부용인 API가 호출자가 하나뿐이라면 체인지로그가 필요한가? 거의 필요 없으며, 그 한 팀에게 보내는 직접 메시지로 보통 충분하다. 체인지로그는 호출자가 하나를 넘어서는 순간, 또는 호출자 목록이 소유 팀을 한 번이라도 놀라게 한 순간부터 제값을 한다. 그것이 기억만으로는 더 이상 믿을 수 없다는 신호이기 때문이다.

내부용 API 변경도 공개용과 같은 리뷰를 거쳐야 하는가? 독자가 외부 호출자가 아니라 동료이므로 표현은 더 가벼워도 되지만, 변경이 브레이킹인지 판단하는 것은 두 경우 모두 같은 주의를 받을 가치가 있다. 내부 호출자에게도 여전히 예전 동작에 의존하는 프로덕션 코드가 있다.

한 번도 추적된 적이 없다면 누가 내부용 API를 호출하는지 어떻게 알아내는가? 소비자 레지스트리가 한 번도 유지되지 않았다면 서버 로그나 서비스 메시의 트래픽 데이터가 정직한 답이다. 그 발견을 일회성 정리가 아니라 레지스트리를 시작하는 순간으로 다뤄라.

슬랙 메시지만으로 충분한가, 아니면 내부용 변경도 정식 체인지로그 항목이 필요한가? 순전히 추가적인 것이 아닌 모든 것에 대해서는 둘 다 필요하다. 메시지는 제때 읽히는 것이고, 항목은 몇 주 뒤 문제를 조사하며 그 메시지를 본 적이 없는 팀이 그래도 찾아낼 수 있는 것이다.

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

changeloop 관련 페이지: 개발자 문서, changelog 도구 비교