[SaaS] 프론트엔드 개발자가 API를 설계하는 이유

Context

노션 문서 기반 API 명세 관리로 인한 코드-문서 불일치 문제가 지속 발생했다. 백엔드 개발자 주도 인터페이스 설계 과정에서 시스템 성능 최적화에 초점이 맞춰져 오버 스펙 인터페이스가 정의되고, 프론트엔드와의 반복 합의로 인한 커뮤니케이션 오버헤드가 발생했다.

Technical Solution

• Google Protocol Buffers(Protobuf)를 IDL로 도입: protoc 컴파일러로 Java, TypeScript 등 다양한 언어로 자동 코드 생성
• 프론트엔드 주도 API 설계 프로세스 전환: 프론트엔드 개발자가 사용자 경험 중심으로 인터페이스 설계, 백엔드 개발자가 기술적 타당성 리뷰
• Git Submodule을 통한 IDL 공유: 생성된 Protobuf 코드를 양쪽 애플리케이션이 동일한 통신 계약 모델로 임포트
• 예약 생성 API 예시: ReserveCommand 메시지에 visitorId(필수), options(필수), memo(선택) 등을 명시해 클라이언트-서버 간 동일한 타입 계약 강제
• Optional 필드 명시적 처리: Protobuf optional 키워드로 Null Handling 로직 필요 여부를 코드 단계에서 명확화

Key Takeaway

IDL을 단순 문서화 도구가 아닌 코드 생성 및 형상 관리 대상으로 삼으면, 클라이언트-서버 간 통신 계약을 강력하게 강제하면서 동시에 프론트엔드-백엔드 간 설계 주도권과 책임을 명확히 할 수 있다. 특히 MSA 환경에서 단일 진실 공급원(Single Source Of Truth) 관리와 파편화 방지에 유효하다.