API 변경 로고: “깨짐”이 보이는 공지 8줄

2025-06-22 · 심다인 · API · 릴리즈 · 문서

2025년 여름, 가명 B2B 팀이 “버전(경로) vs 헤더”를 동시에 쓰다 문서/실서버/지원팀이 서로 다른 “마지막 날”을 떠올렸습니다. 이 글에선, 공지 8줄(누구·무엇·언제·롤백/호환/연락)을 스프레드시트에만 두지 말고, 퍼블릭/내부/온콜이 읽는 문장 1쌍으로 압축한 사례를 씁니다. 구체 API명·사명·계약은 생략합니다.

둘째, “에러(코드) 사전”이 길어질수록, 파트너는 FAQ가 아닌, 자기 기준의 5줄로 줄입니다. “우리 쪽 5줄+당신 쪽 5줄”이 맞는지(개념)를 멘토링에서 자주 봤습니다. 문서/코드/지원팀 3갈래가 5줄로 줄어드는 2주(가명) 루틴이 있습니다.

셋째, SLO, 레이트, 쿼터, 비용(트래픽)은 “말(외부)과 측정(내부)”이 달르면, RC·사고·포스트모텀의 첫 30분이 “지표 뜻” 싸움이 될 수 있다는 메모. 외부에 말하는 문장(가명) 1p와, 내부 SLO(가명) 1p를 “같은 날, 같은 티”에 맞춰 두는 팀이 덜 흔들렸다는 관찰.

넷째, 본문은 “계약, SLA, 법, 최종 감독/규정 해석”이 아닙니다. API 거버넌스·런·커뮤의 내부 러닝 메모에 가깝고, 팀/법무/영업/파트너의 확정·서명/공지/제출 절차는 별도입니다. 최종 “공지/중단/절대 일정”은 팀/파트너가 합의·확정합니다.