전산에 API를 처음 붙일 때, 어디까지 열어야 할까

매출 전산을 맡을 때, 팀 안에서 자주 나온 말이 있었다.
‘이제 API로 가자.’

막상 설계를 시작하니, 어디까지 API로 열지가 더 어려웠다. 회의실에서는 모두가 고개를 끄덕였지만, 화면 하나를 API로 빼기 시작하는 순간부터 ‘이 필드도 넣을까’ 싸움이 반복됐다.

왜 경계를 먼저 고민했는가 (이유)

‘일단 다 열자’ — 처음엔 그게 편해 보였다

처음엔 ‘일단 다 열자’ 쪽이 편해 보였다. 새로운 구조를 빨리 보여주고 싶은 마음이 컸기 때문이다. Spring Boot로 옮기는 그림도, swagger를 붙인 모습도, 팀 밖에 보여주기엔 멋졌다.

그런데 몇 주 지나니 편함의 대가가 한꺼번에 돌아왔다.

화면마다 달라진 같은 API

응답 필드가 화면마다 달라졌다. ‘이 화면만’ 필드를 추가하다 보니 같은 API가 화면 수만큼 분기됐다. 코드 리뷰에서 ‘이건 이 화면 전용이에요’라는 말이 늘었고, 나중에 필드 이름을 바꾸려 할 때 누가 깨지는지 아무도 확답하지 못했다.

문서가 코드보다 늦게 따라온 날

스펙 변경 때 소비자(웹/배치/연계)가 동시에 깨졌다. swagger를 붙이기 전까지는 ‘코드가 곧 문서’였고, 그 문서는 매번 거짓말을 했다. 배포는 됐는데 연계 쪽에서 ‘스펙이 바뀐 줄 몰랐습니다’라는 전화가 오면, 그날은 API가 아니라 신뢰를 고치는 일이 됐다.

그때 깨달았다. API는 ‘만들기’보다 유지하기가 더 비싸다는 걸.
그래서 당시 결론은 단순했다. 다 여는 게 아니라, 책임질 수 있는 만큼만 연다.

비슷한 경험 — B2B 알림톡·외부 연계

이후 B2B 알림톡과 외부 플랫폼 연동을 붙일 때 같은 고민이 반복됐다. 차이라면, 이번엔 소비자가 사외(파트너) 라는 점이었다.

내부 화면은 깨지면 우리가 밤새 고치면 됐다. 파트너에게 나간 계약은 ‘내일 배포로 고칠게요’가 통하지 않았다. 새 기능을 빨리 열고 싶은 욕심이 가장 위험해지는 지점이었다.

당시 결론: 외부에 노출하는 계약은 최소 범위 + 버전 고정으로 시작하고, 내부 편의 필드는 절대 섞지 않기로 했다. ‘연계 표준화’라는 이름으로 입출력 형태와 에러 코드를 한곳에 모았다.
이 경험을 거치고 나서야, 경계 설정이 ‘기술 취향’이 아니라 변경 비용을 누가 떠안느냐의 문제라는 걸 분명히 알았다. 내부 DTO에 편하게 필드 하나 더 넣는 순간, 그 비용은 조용히 밖으로 넘어갈 수 있었다.

지금의 기준 (당시 결론을 어떻게 지키는가)

외부/배치가 꼭 필요한 계약만 먼저 고정했다. ‘나중에 필요하면 추가’가 아니라 ‘지금 꼭 필요한 것만’.
DTO와 화면 모델을 분리했다. 화면이 바뀌어도 API 계약이 같이 흔들리지 않게.
변경 시 영향 범위를 말로 설명할 수 있어야 통과시키기로 했다. ‘누가 깨지는지’를 한 문장으로 못 말하면, 그 변경은 아직 준비가 안 된 것이다.

아직 부족한 것 (개선점)

API 버전 정책은 정했지만, 구버전 폐기(deprecation) 일정을 강제하는 절차는 약하다. 옛 계약이 계속 살아남는다.
소비자 목록(누가 이 API를 쓰는가)을 코드/문서로 추적하지 못해, 여전히 변경 영향도를 사람이 수소문한다.
계약 변경 시 자동으로 깨짐을 잡아주는 계약 테스트가 없어, 배포 후에야 문제를 발견하는 경우가 있다.

앞으로 나가야 할 방향

API에 버전 + 폐기 일정을 명시하고, 구버전 사용량을 측정해 안전하게 닫는 흐름을 만든다.
외부 계약은 계약 테스트(consumer-driven) 를 붙여, ‘바꾸면 누가 깨지는지’를 배포 전에 자동으로 안다.
새 시스템을 Spring Boot로 이관하면서, 화면용 BFF와 외부 연계용 API의 경계를 구조적으로 분리한다.
개발자센터에 API 문서를 자동 생성으로 연결해, ‘문서가 코드보다 늦는’ 문제를 반복하지 않는다.

완벽한 API 플랫폼은 아직 아니다.
하지만 ‘처음 API’의 의미를, 확장 가능한 경계로 이해하게 됐다. 다음 목표는 그 경계를 내 설명이 아니라 도구가 지켜주는 상태로 옮기는 것이다.