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

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

막상 설계를 시작하니, 어디까지 API로 열지가 더 어려웠다.

고민 포인트

• 화면 전용 조회까지 API로 만들 것인가
• 외부 연계에 필요한 최소 범위만 열 것인가
• 내부 배치와 웹이 같은 계약을 쓸 것인가
• 버전 관리를 처음부터 넣을 것인가

처음엔 ‘일단 다 열자’ 쪽이 편해 보였다. 새로운 구조를 빨리 보여주고 싶은 마음이 컸기 때문이다. 하지만 그 편함의 대가는 나중에 한꺼번에 돌아왔다.

현실에서 부딪힌 것 (당시 결론)

• 응답 필드가 화면마다 달라졌다. “이 화면만” 필드를 추가하다 보니 같은 API가 화면 수만큼 분기됐다.
• 스펙 변경 때 소비자(웹/배치/연계)가 동시에 깨졌다. 누가 이 API를 쓰는지조차 한눈에 안 보였다.
• 문서가 코드보다 늦게 따라왔다. swagger를 붙이기 전까지는 “코드가 곧 문서”였고, 그 문서는 매번 거짓말을 했다.

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

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

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

• 이유: 내부 화면은 깨지면 우리가 고치면 되지만, 외부 연계는 한 번 공개한 계약을 마음대로 바꿀 수 없었다. 새 기능을 빨리 열고 싶은 욕심이 가장 위험해지는 지점이었다.
• 당시 결론: 외부에 노출하는 계약은 최소 범위 + 버전 고정으로 시작하고, 내부 편의 필드는 절대 섞지 않기로 했다. “연계 표준화”라는 이름으로 입출력 형태와 에러 코드를 한곳에 모았다.
• 이 경험을 거치고 나서야, 경계 설정이 “기술 취향”이 아니라 변경 비용을 누가 떠안느냐의 문제라는 걸 분명히 알았다.

지금의 기준

• 외부/배치가 꼭 필요한 계약만 먼저 고정했다.
• DTO와 화면 모델을 분리했다.
• 변경 시 영향 범위를 말로 설명할 수 있어야 통과시키기로 했다.

아직 부족한 것 (개선점)

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

앞으로 나가야 할 방향

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

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