[Project] API-First Design의 필요성

API-First Design의 필요성

"저쪽 팀이 무너졌다고 해서 구경하러 갔죠. 그런데 보고 오니 우리 팀이 무너져 있는 거예요. 보자마자 눈물이 났습니다."

 

프로젝트를 진행하다 보면 흔히 겪는 상황입니다. 각자 열심히 개발했는데, 막상 합치려고 보니 규격이 맞지 않고,

에러는 터지고, 수정하느라 밤을 새우는 악순환. 도대체 API가 뭐길래 우리를 이렇게 힘들게 하는 걸까요?

이번 포스팅에서는 단순한 인터페이스 구현을 넘어, 프로젝트의 성패를 가르는 'API-First Design' 접근법에 대해 정리해 봅니다.

---

1. API는 단순한 코드가 아니라 '약속(Promise)'이다

많은 주니어 개발자들이 API를 단순히 "프론트엔드에서 요청하면 백엔드가 데이터를 주는 구멍" 정도로 생각합니다.

하지만 API의 본질은 개발자 간의 약속입니다.

단순한 인터페이스 앞에는 매우 큰 준비가 필요합니다.

• 데이터 검증: 실제 이 데이터가 구현 가능한가?
• UI/UX 고려: 화면에 필요한 데이터가 빠짐없이 포함되었는가?
• 재사용성: 다른 화면에서도 쓸 수 있는 구조인가?
• 테스트: 예외 상황에 대한 처리는 정의되었는가?

이러한 고민 없이 코드부터 짜기 시작하면, 결국 프론트엔드와 백엔드 사이의 '신뢰'가 깨지고,

이는 곧 프로젝트의 붕괴(팀의 붕괴)로 이어집니다.

---

2. 왜 API-First Design인가?

API-First Design이란, 코드 구현 이전에 API의 규격과 동작을 가장 먼저 설계하는 방법론을 말합니다.

"왜 하필 API가 첫 번째여야 할까요?" 현재의 웹/앱 개발은 철저한 분업과 협업이 기본이기 때문입니다.

API 설계가 선행되면 다음과 같은 이점을 얻을 수 있습니다.

 

1. 개발 효율성 개선 & 비용 절감: 재작업(Rework)을 획기적으로 줄여줍니다.
2. 병렬 개발 가능: 규격이 정해지면 백엔드가 로직을 짜는 동안,
   프론트엔드는 모킹(Mocking) 데이터를 이용해 화면을 동시에 개발할 수 있습니다.
3. 협업 능력 증가: 개발 이전 단계에서 팀원 간의 이해도를 일치시킬 수 있습니다.

---

3. 협업의 두 가지 갈림길: 비동기 vs 동기

API를 중심으로 협업을 진행할 때, 크게 두 가지 스타일이 존재합니다.

상황에 맞춰 이 둘을 적절히 섞어 쓰는 지혜가 필요합니다.

출처 : https://adrianmejia.com/

① 비동기식 진행 (Asynchronous)

"모든 선수가 각자 시간에 맞춰 출발하되, 도착지에서 만나는 방식"

• 방식: 미리 정의하여 문서화된 API(설계)를 기준으로, 상호작용 없이 각자 개발합니다.
• 장점: 백엔드 개발이 완료되지 않아도 프론트엔드 작업이 가능합니다. 전체적인 출시 시간을 단축할 수 있습니다.
• 단점: 초기 설계가 부실하면 재앙이 닥칩니다.
  나중에 합쳤을 때 규격이 다르면, 수정하는 데 드는 비용이 기하급수적으로 늘어납니다.

② 동기식 진행 (Synchronous)

"앞선 선수가 바통을 넘겨줘야만 다음 선수가 출발하는 이어달리기 방식"

• 방식: 백엔드가 배포를 하고, 프론트엔드가 그걸 받아서 테스트하고 피드백을 주는 '핑퐁' 방식입니다. (CI/CD 환경 필수)
• 장점: 즉각적인 동작 확인이 가능하고, 오류를 바로 잡을 수 있습니다.
• 단점: 백엔드가 막히면 프론트엔드도 놉니다. 잦은 커뮤니케이션 비용으로 프로젝트 속도가 느려질 수 있습니다.

💡 결론: 하이브리드가 답이다.

 

로버트 C. 마틴의 <클린 아키텍처>에서는 "릴리즈 후반부로 갈수록 수정 비용은 증가하고 생산성은 감소한다"고 경고합니다.

따라서 초기 단계(설계)에서는 비동기식으로 철저하게 규격을 맞춰 병렬 개발을 하고,

통합 단계에서는 동기식으로 빠르게 피드백을 주고받는 혼용 전략이 가장 유효합니다.

---

4. API 설계, 문서 한 장이면 되나요?

"API 설계하라고 해서 Swagger(또는 Notion)에 URL만 적어놨는데요?" 이것은 반쪽짜리 설계입니다.

API-First Design을 제대로 실현하기 위해서는 다음 문서들이 유기적으로 연결되어야 합니다.

이 모든 문서는 "개발자들의 이해도(Sync)를 맞추기 위한 도구"입니다.

 

1. Wireframe (와이어프레임):
   • FE의 개발 범위를 BE가 시각적으로 이해하는 단계.
   • "아, 이 버튼을 누르면 저 데이터가 필요하겠구나"를 미리 파악합니다.
2. 기능 명세서:
   • 와이어프레임을 글로 옮긴 것. 요구사항과 제한사항(Validations)을 정의합니다.
   • FE는 구현 가능성을, BE는 로직 설계를 검토합니다.
3. API 연동 규격서:
   • 가장 중요한 약속의 문서. 정상 응답뿐만 아니라 에러 케이스까지 상세히 정의해야 합니다.
4. ERD (개체 관계도):
   • API 규격서의 데이터가 실제 DB에 저장될 수 있는지 검증합니다.
5. Sequence Diagram:
   • UI 클릭부터 DB 저장까지 데이터의 흐름을 한눈에 봅니다. 로직의 빈틈을 찾기에 최적입니다.
6. Gantt Chart:
   • 누가, 언제, 무엇을 할지 정합니다. 설계된 내용을 바탕으로 현실적인 일정을 산출합니다.

---

5. 마치며: 준비된 자만이 '칼퇴'를 누린다

처음에 질문했던 "왜 API가 첫 번째인가?"에 대한 대답을 다시 해보겠습니다.

단순히 API 문서를 먼저 만드는 것이 중요한 게 아닙니다.

와이어프레임부터 ERD까지, 전체 흐름을 꿰뚫어 보고 팀원들과 합의하는 그 모든 준비 과정이 바로 API-First Design입니다.

 

초반의 설계 시간이 아깝게 느껴질 수도 있습니다.

당장 코드를 치고 싶어 손이 근질거릴 수도 있습니다.

하지만 명심하세요.

코딩을 시작하기 전의 1시간이, 마감 전날의 밤샘 10시간을 아껴줍니다.

 

우리 팀이 무너지는 것을 보고 싶지 않다면, 지금 당장 팀원들과 모여 '약속'부터 점검해 보는 건 어떨까요?