2강. MSA에서 API는 팀 간 외교 문서다

🤔 Question

👉 MSA로 전환하면 가장 먼저 듣는 말이 있습니다.
"이제 서비스끼리는 API로 통신하면 돼요."

겉보기엔 단순합니다.
서비스 A가 서비스 B의 API를 호출하면 끝.

하지만 실무에 들어가면 곧 깨닫습니다.
👉 MSA에서 API는 단순한 기술 연결이 아니라, 팀과 팀 사이의 외교 문서라는 사실을요.

 

🎯 모놀리식에서는 몰랐던 문제

모놀리식 시스템에서는
같은 코드베이스, 같은 팀, 같은 배포 주기.

메서드 이름을 바꾸거나
DTO 필드를 수정해도
같은 팀이 함께 수정하면 끝입니다.

하지만 MSA에서는 다릅니다.
👉 API 변경은 다른 팀의 일정, 배포, 장애로 직결됩니다.

 

🎯 팀과 팀은 이제 독립 국가

MSA 조직에서 각 팀은
하나의 독립된 국가와 같습니다.

✔ 자체 일정
✔ 자체 기술 스택
✔ 자체 배포 파이프라인

이때 API는
👉 국가 간 체결하는 외교 협약입니다.

외교 협약은 함부로 바꿀 수 없습니다.
일방적으로 조항을 수정하면
외교 분쟁이 발생합니다.

API도 같습니다.
계약을 깨면 다른 팀 서비스가 멈춥니다.

 

🎯 실제 현장에서 벌어지는 외교 실패

{
  "orderId": 1001,
  "amount": 15000
}

결제팀은 어느 날 응답 구조를 바꿉니다.
"필드명을 더 명확하게 했어요."

{
  "orderId": 1001,
  "totalAmount": 15000
}

프론트팀은 아무것도 모르고 있다가
결제 화면이 전부 깨집니다.

👉 이것이 API 외교 문서가 깨진 순간입니다.

 

🎯 외교 문서는 신뢰가 핵심

좋은 외교 문서는
상대가 믿고 개발할 수 있어야 합니다.

✔ 언제 호출해도 같은 형태로 응답
✔ 예외 상황도 예측 가능
✔ 변경 시 충분한 협의

API도 동일합니다.
👉 신뢰 가능한 계약이 팀 생산성을 결정합니다.

 

🎯 그래서 Contract-First가 중요하다

MSA에서 API를 먼저 구현하고
나중에 문서를 맞추는 방식은 위험합니다.

👉 계약(Contract)을 먼저 정의하고
👉 모든 팀이 이를 기준으로 개발해야 합니다.

이것이 Contract-First 개발이며,
팀 간 외교 문서를 공식화하는 과정입니다.

 

☔ 정리

👉 MSA에서 API는 단순 호출 수단이 아닙니다.
👉 팀과 팀 사이의 외교 문서입니다.
👉 신뢰 없는 계약은 곧 장애와 갈등으로 이어집니다.

API 설계는 기술 설계가 아니라
조직 협업 설계입니다.

 

 

If I was of any help to you, please buy me coffee 😿😢😥

If you have any questions, please leave them in the comments

Buy me a coffee

▶ Youtube Sub

🧭 References

[1] reference : https://doctorson0309.tistory.com/

[2] Ads : https://apps.apple.com/us/app/beluga-classic-film-filters/id6744041061