프론트에서 API 스펙이 확정되기까지 백엔드와 협업하며 배운 현실적인 팁

프론트엔드 개발을 하다 보면 이런 상황을 종종 마주하게 됩니다.

“API 스펙은 회의에서 어느 정도 이야기했는데… 문서는 아직 정리 중. 백엔드 개발은 다음 주 시작.”

하지만 프론트 개발 일정은 이미 시작되었고, 화면 구성도 어느 정도 나와 있는 경우가 많죠.
데이터를 받아 UI 동작을 만들기 위해서는 더 이상 API를 기다릴 수 없습니다. 현실적으로 프로젝트 일정은 그렇게 넉넉하지 않기 때문입니다.

그래서 저는 API 스펙 초안을 바탕으로 인터페이스만 먼저 맞추고, MSW(Mock Service Worker)를 사용해 개발을 진행하는 방식을 많이 사용해왔습니다.

이 글에서는 제가 백엔드 팀과 협업하면서 겪은 경험을 바탕으로, API 확정 과정에서 고려할 점, MSW를 활용하는 이유, 그리고 실무에서 느낀 현실적인 팁들을 공유드리고자 합니다.

완벽한 API 스펙을 회의에서 기대하지 않습니다

API 회의를 하면 종종 이런 흐름이 나옵니다.

🙂 BE: 구조는 이렇게 생각하고 있어요.
🤔 FE: UI 요구사항이 바뀌면 필드가 더 필요할 수도 있어요.
😅 PM: 이 부분은 기획이 바뀔 수도 있어요.

초기 기획은 완전히 확정되지 않은 상태이고, 기능은 계속 변할 수 있습니다.
회의 초반부터 모든 케이스와 필드를 완벽하게 정의하려 하면 회의만 길어지고 생산성이 떨어집니다.

그렇기 때문에 저는 전체적인 구조와 필요한 핵심 필드를 우선 맞추는 방식을 더 선호합니다.
이 단계에서는 확정본이 아니라 “가안”에 가깝다는 점을 서로 공유하는 것도 중요합니다.

왜 간단한 인터페이스만 맞추고 먼저 개발을 시작할까요?

그 이유는 아주 단순합니다.

백엔드 API가 완성될 때까지 기다리면 프론트 일정이 지연되기 때문입니다.

프론트 개발은 다음과 같은 단계를 거칩니다.

• UI 개발
• 상태관리 및 요청 로직 작성
• 데이터 연동
• 예외 처리
• QA 및 디버깅

이 단계들을 순차적으로 진행해야 하기 때문에, API가 늦어질수록 모든 일정이 밀리는 구조입니다.
그래서 가장 현실적인 방식은 아래 흐름입니다.

1. API 스펙 초안 공유
2. 필요한 인터페이스 정의
3. MSW로 Mock API 구성
4. 프론트 개발 진행
5. 실제 API 연동 및 수정 보완

이 방식의 가장 큰 장점은 백엔드와 프론트가 병렬로 개발할 수 있다는 점입니다.

왜 Mocking이 필요할까요?

Mock 없이 개발을 진행하면 이런 상황이 흔히 발생합니다.

• API가 나오지 않아 UI 작업이 지연됨
• 스테이징 서버가 불안정하면 테스트 불가능
• 데이터가 준비되지 않아 통신 흐름 테스트가 안됨

반면 Mock을 사용하면 다음과 같은 장점이 생깁니다.

• API 없이도 UI 개발과 테스트가 가능
• 백엔드 개발 속도와 무관하게 작업 가능
• API가 나오면 연결만 하면 되기 때문에 리스크 감소

그리고 이 Mocking을 가장 유연하게 도와주는 도구가 MSW(Mock Service Worker) 입니다.

MSW를 사용할 때 주의하면 좋은 점

MSW는 강력한 도구지만, 다음 사항을 신경 쓰면 더 효과적으로 사용할 수 있습니다.

1. 실제 API가 업데이트되면 Mock도 함께 업데이트하기

Mock이 오래되면 API 연동 단계에서 예상치 못한 수정 비용이 발생합니다.
Mock과 API 명세는 되도록 항상 동기화하는 것이 좋습니다.

2. 정상 응답만 Mock하지 않기

실제 서비스 환경에서는 성공 응답보다 다양한 예외가 더 자주 발생합니다.

• 인증 실패
• timeout
• 입력값 오류
• nullish 한 값이 올 경우

이런 케이스를 미리 Mock으로 테스트해두면 안정적인 UI를 만드는 데 큰 도움이 됩니다.

3. 개발 환경과 테스트 환경에서 Mock 성격을 분리하기

이렇게 목적에 따라 Mock을 나누어 두면 유지보수가 훨씬 편해집니다.

백엔드와 협업할 때 도움이 되었던 팁

마지막으로 협업하면서 몸으로 느낀 팁을 정리하면 아래와 같습니다.

• 문서는 꼭 남겨두기 (Notion, Swagger, Jira(Confluence) 등 어떤 도구든 괜찮습니다)
• 필드는 삭제보다 추가 중심으로 설계하면 협업이 수월합니다
• API 명세와 실제 응답이 다르면 바로 공유하기
• 프론트에서 원하는 response shape을 먼저 제안하면 논의가 더 빨라집니다
• API 구조가 아니라 사용자 흐름 기반으로 이야기하기

마무리

API 스펙은 한 번 정하면 끝나는 문서가 아니라, 서비스와 함께 계속 발전하는 문서입니다.
변경이 자연스러운 영역이기 때문에, 너무 완벽하게 맞추려고 하기보다는 변경에 유연한 협업 방식이 중요하다고 생각합니다.

Mock 데이터를 활용한 병렬 개발 방식은 그런 의미에서 현실적이고 효율적입니다.
실제 API를 기다리지 않고도 개발을 진행할 수 있고, 이후 연동 과정에서도 큰 혼란 없이 마무리할 수 있기 때문입니다.

이 방식이 API 기반 협업을 겪는 프론트엔드 개발자분들께 도움이 되길 바랍니다.
읽어주셔서 감사합니다.