API 퍼스트, MSA 실전 가이드

가게가 커질수록 문제는 메뉴가 아니라 연결입니다. 해봤더니 POS, 배달, 멤버십이 얽히는 순간 변경 한 번이 전 지점에 영향 주더라고요. 그래서 질문은 하나로 모입니다. ‘우리는 무엇을 약속하고, 그 약속을 코드로 어떻게 고정할 것인가?’ API 퍼스트는 그 약속을 먼저 정의하고 화면은 나중에 붙이는 방식입니다. 실제로는 이 순서가 바뀌면 기능이 늘수록 속도와 품질이 동시에 무너집니다.

드러커는 “측정되지 않으면 관리도 안 된다”고 했습니다. 경험상 API 명세가 곧 측정 가능한 서비스 약속입니다. 요청·응답 스키마, 에러 코드, 멱등성, 속도 목표를 ‘버전과 함께’ 제품처럼 관리해야 합니다. 화면 요구가 바뀌어도 계약이 유지되면 백엔드는 안전합니다. 반대로 계약이 없으면 매번 화면에 끌려다니며 의존성이 폭증합니다.

실제로는 경계가 성능입니다. 주문, 결제, 재고, 고객처럼 도메인별로 마이크로서비스를 쪼개고 팀 소유권을 1:1로 맞춥니다. 포터가 말한 ‘전략은 포기의 연속’처럼, 한 서비스가 하지 않을 일을 선명히 정해야 결합이 느슨해집니다. 경험상 이 경계가 흐리면 배포 때마다 연쇄 테스트와 핫픽스가 끝이 없습니다.

해봤더니 장애는 동기 호출 체인에서 연쇄로 터집니다. 핵심 흐름(주문 생성)은 동기로 최소화하고, 나머지(알림, 포인트 적립, 추천)는 이벤트로 비동기 처리하세요. 큐·리트라이·서킷브레이커로 실패를 격리하면 피크타임에도 버팁니다. 추적성은 필수라서 상관ID로 로그·트레이스를 묶어두면 원인 파악 속도가 두 배 빨라집니다.

SLO(가용성·지연·오류율)를 먼저 정하고, 버저닝은 하위호환을 기본으로 합니다. 실전에서는 기능깃발(feature flag)로 점진 배포, 카나리로 리스크를 쪼갭니다. 콜린스의 ‘플라이휠’처럼 릴리스 주기를 짧게 돌려 작은 승리를 누적하세요. 폐기 정책과 지원 종료 일정까지 공개하면 파트너 신뢰가 올라가고 변경 비용이 예측 가능해집니다.

부산의 12개 점포 카페를 묶을 때, 경험상 화면부터 맞추니 매주 규칙이 깨졌습니다. API 퍼스트로 주문·결제·쿠폰을 분리하고 POS는 소비자였습니다. 결과적으로 주문 오류율 30%→5%, 신규 프로모션 출시 주기 4주→1주, 교육시간 40% 단축. 무엇보다 가맹점별 커스텀을 계약 밖 확장포인트로 처리해 본사 배포와 갈등이 줄었습니다.

단일 서버로 버티던 배달 매장이 피크에 500ms 이상 지연으로 주문 누락이 났습니다. 실무에서 주문·배차·정산을 우선 분해, 이벤트로 연결하고 캐시·읽기분리를 적용했더니 평균 응답 450ms→180ms, 주말 장애 3회→0. 클라우드 비용은 15% 늘었지만 환불 감소와 회전율 개선으로 매출이 22% 늘어 총마진이 개선됐습니다.

0~2주: 현재 흐름을 API 인벤토리로 추출, 핵심 엔드포인트 10개 안으로 축소. 3~4주: 주문 API에 멱등키·표준 에러 도입, 문서 자동화. 5~8주: 인증·권한(OAuth2)과 관측(로그·트레이스) 기본 깔기. 9~12주: 주문/결제 서비스 분리, 이벤트 브로커 도입. 13~16주: 버전정책·폐기사이클 공지. 17~24주: 카나리·플래그로 배포 자동화.