채널톡 Open API 뜯어고치기
Summary
코드 수정 없이 문서 실시간 반영까지! 채널톡이 API 개발을 Design-First로 뜯어고친 이유
내부 비즈니스 모델과 외부 API의 강한 결합을 풀고, Go 서버 분리와 AI 에이전트(MCP) 연동까지 달성한 여정
본 아티클은 채널톡 백엔드 팀이 기존 Code-first 방식의 한계를 느끼고, 스펙과 문서의 불일치를 근본적으로 해결하기 위해 Design-first로 전환한 아키텍처 혁신을 소개합니다. 메인 서버에 묶여 있던 배포 주기를 탈피하고자 별도의 Go 기반 Open API 서버를 구축하였으며, 내부 도메인 모델과 외부 스펙을 완벽하게 격리했습니다. 나아가 고도화된 스펙 문서를 바탕으로 AI 생태계인 MCP(Model Context Protocol)까지 원활하게 연동한 실무 노하우를 담고 있습니다.
- 01문서와 코드 스펙의 불일치를 해결하기 위해 API 개발 패러다임을 Code-first에서 Design-first로 대대적 전환
- 02Go 기반 Open API 전용 서버를 신설하여 메인 Java 서버의 배포 주기(평균 일주일)와 문서 업데이트 프로세스를 완전히 분리
- 03공개 리소스용 프로토콜 버퍼(Protobuf) 모델을 스키마 기준으로 삼아 내부 구현의 변경이 외부 고객 계약에 영향을 주지 않도록 결격 처리
- 04가독성과 API 직접 호출(Try It) 경험이 뛰어난 오픈소스 도구 'Scalar' 선택 및 다국어 번역 누락 방지를 위한 검증 파이프라인 CI 구축
- 05완성도 높은 OAS 명세를 기반으로 AI 에이전트가 도구처럼 API를 사용하는 MCP(Model Context Protocol) 규격 연동 성공
RECOMMENDATION
내부 시스템 리팩토링 시 외부에 노출된 공개 API가 깨질까 걱정하는 백엔드 개발자나, 개발 단계에서 기획자·프론트엔드와 API 명세를 미리 맞추고 병렬 개발을 진행하고 싶은 팀에게 이 아키텍처 패턴을 강력히 권장합니다.
The Problem
기존 채널톡 Open API는 Java 코드의 어노테이션에서 명세를 추출하는 Code-first 방식으로 동작하여 가이드 문서와 실제 동작 간 불일치가 발생했고, 사소한 문구 수정에도 메인 서버 재배포가 필요해 평균 일주일이 소요되었습니다. 또한, 서버 내부 모델이 고객 응답 객체에 직접 노출되어 내부 구현 변경이 외부 API 계약을 의도치 않게 깨뜨리는 강한 결합 문제가 있었습니다.
The Solution
OAS(OpenAPI Specification)를 우선 작성하는 Design-first 방식으로 전환하고, 이를 기반으로 oapi-codegen을 사용해 Go 타입 및 인터페이스를 생성하는 독립적인 Go 기반 Open API 서버를 구축했습니다. 내부 모델과 공개 API 계약을 분리하기 위해 프로토콜 버퍼(Protobuf)로 공개 리소스 모델을 정의하고, Open API 서버가 여러 내부 Core API를 호출 및 조합하여 최종 REST 응답을 반환하도록 아키텍처를 개선했습니다.
The Result
총 85개의 신규 REST API와 다국어(영어/한국어) 기술 문서, 실시간 호출 테스트(Scalar 이용) 기능을 성공적으로 오픈하였으며, 하루 평균 약 191만 건의 API 요청을 처리하고 있습니다. 또한 명세 검증을 CI 단계에서 자동화하고 AI 에이전트가 API를 직접 호출하도록 돕는 MCP(Model Context Protocol) 및 AI 상담사 ALF 연동까지 완료했습니다.
Trade-off
Design-first 패러다임 전환으로 인해 OAS 규격 학습 및 코드 제너레이터 등 신규 도구 도입에 따르는 초기 엔지니어링 비용이 발생했습니다. 또한, 관리 효율화를 위해 AppStore의 RPC형 호출 방식(Native Function)과 통합하려 했으나 기존 REST API 연동 고객의 전환 비용 및 부담을 고려해 별도의 REST 인터페이스 레이어를 계속 유지하는 중복 관리 비용을 수용했습니다.