JaramGroupware Hub API

개요

JaramGroupware Hub는 학회 구성원을 위한 커뮤니티 서비스 API다. 기존 Django 기반 서비스 구조를 FastAPI 중심으로 재구성하면서, API 계층과 문서 체계를 정리하는 작업을 수행했다.

저장소

https://github.com/msng-devs/JGW-hub

프로젝트 배경

이 프로젝트의 핵심은 기존 커뮤니티 기능을 더 명확한 API 구조로 다시 정리하는 것이었다. 단순 게시판이 아니라 학회 내부 서비스로 붙는 API였기 때문에,

• 문서화
• 응답 구조 일관성
• 테스트 가능성
• 유지보수성

을 함께 고려해야 했다.

왜 FastAPI였는가

JGW Hub에서는 기존 Django 기반 구현을 FastAPI로 재구성했다. 이유는 다음과 같다.

• OpenAPI 기반 문서 생성이 자연스럽다.
• API 서버로서 필요한 경량성과 생산성이 높다.
• 타입 힌트 기반 개발 경험이 좋아서 팀 협업 시 계약을 맞추기 쉽다.
• 프로젝트 리빌드의 필요성을 판단했던 시점이 학회 내부 사정으로 가용 리소스 규모가 매우 크게 줄었던 시점이었기에 너무 무거운 Django보다 빠르고 가볍게 구현할 수 있는 FastAPI로 PoC를 진행하는 것이 현실적이었다.

특히 이 프로젝트에서는 API 문서가 실제 사용자를 위한 산출물이었기 때문에, FastAPI의 문서 자동화 장점이 크게 작용했다.

구현에서 중요했던 점

API 계약 정리

단순히 엔드포인트를 만드는 것이 아니라, 클라이언트가 예측 가능한 응답을 받도록 API 계약을 정리했다.

문서와 실제 응답 구조가 어긋나지 않도록 신경 쓴 이유는, 학회 내부 프로젝트일수록 "구두 설명"에 의존하기 쉬운데 그런 방식은 유지보수에 불리하기 때문이다.

인수인계 받았던 문서에서도 실제 endpoint와 문서의 내용이 다른점이 많았어서 직접 endpoint에 요청을 날려가며 최신화 작업을 수행했다.

SQLAlchemy 기반 데이터 접근

도메인 로직과 DB 접근을 분리하고, 조회/쓰기 코드를 더 명시적으로 관리하려고 SQLAlchemy를 사용했다. ORM 계층을 명시적으로 다루는 쪽이 이후 확장이나 테스트에서 유리하다고 판단했다.

문서화

GitBook 문서와 OpenAPI 산출물을 함께 관리했다. 서버 호스트를 24/7 계속 유지할 수 있었다면 GitBook이 없어도 되었겠지만 당시 서버 유지 가능성이 불확실했기 때문에 인수인계와 협업을 고려해서 GitBook을 추가 도입했다.

역할

• FastAPI 기반 API 재구성
• SQLAlchemy 계층 정리
• 테스트 코드 작성
• API 문서화 및 배포 자동화

프로젝트를 통해 얻은 것

JGW Hub는 규모가 큰 프로젝트는 아니었지만, 내게는 **"기존 서비스를 다른 프레임워크로 다시 옮겨 보는 경험"**이라는 점에서 의미 있었다. 새로 만드는 것보다 재구성은 고려해야하는 관점이 달랐는데, 기존 사용 패턴과 응답 형태를 유지해야한다는 점이 살짝 어렵게 느껴졌다.

배운 점

• 마이그레이션은 새로 만드는 것보다 호환성을 지키는 일이 더 어렵다.
• API 문서는 구현이 끝난 뒤 적는 요약이 아니라, 재구성 과정과 구현, 기획 등 핵심 단계 모두를 통틀어 가장 중요한 기준점이다.