오늘은 기능 요구사항과 예외 사항 정책서, ERD를 기반으로 API 명세서를 작성하는 방법에 대해 설명해보겠다.
(오늘 내용은 개인적인 견해와 방식이다.)
컨트롤러를 끊는 방식은 크게 4가지로 나뉜다.
- 자원 중심(URL의 명사)
- 행위 중심(사용자의 행위)
- 화면 중심(프론트 페이지)
- CRUD 통합(없음)
자원 중심
/workspaces → WorkspacesController
/workspaces/members → WorkspaceMembersController
/tasks → TasksControllerURL의 명사를 기준으로 자른다.
Rest원칙이 가장 가까우면서, API의 태그 분류가 명확해진다. 도메인이 많을 때 적합하다.
그러나 컨트롤러의 수가 많아진다.
행위 중심
LoginController → 로그인, 로그아웃, 토큰 갱신
InviteController → 멤버 초대, 수락, 취소
AssignController → 이슈 담당자 지정, 변경사용자의 행동을 기준으로 자른다.
요구사항 문서와 1:1 대응에 용이하다. 이는 기획자와의 소통이 쉽다는 장점을 가질 수 있겠다.
그러나 자원이 여러 컨트롤러에 분산되어 유지보수가 어렵고, URL 설계가 Rest답지 않을 수 있다.
화면 중심
DashboardController → 대시보드 화면에 필요한 모든 데이터
ProjectDetailController → 프로젝트 상세 화면용 API 묶음FE를 위한 BE방식이라고 보면 된다. 페이지 단위를 기준으로 자른다.
FE 개발자가 한 컨트롤러만 보면 되어서 협업이 쉽다.
그러나 화면이 변경되면 BE도 변경될 수 있고, 로직의 중복이 생긴다.
CRUD 통합 중심
AuthController → login, logout, signup, withdraw, oauth, refresh 전부작은 프로젝트나 초기 프르토 타입에서 용이하다.
그러나 파일이 커지면서 수정할 때 어디를 건드려야할지 파악이 어려워지고 Guard 선언이 메서드마다 달라진다.
- Guard: NestJS에서 요청 통과를 결정하는 관문이다.
실제 작업 순서
① ERD 보고 테이블군 파악
↓
② FK 방향 + 라이프사이클로 모듈 결정
↓
③ 자원/Guard/변경이유 기준으로 컨트롤러 분리
↓
④ 컨트롤러에 엔드포인트 배치
↓
⑤ 각 엔드포인트에 API 명세 작성필자는 위와 같은 작업 순서로 먼저 큰 모듈을 정리하고 컨트롤러에 엔드포인트를 배치하는 형식을 사용했다.
쉽게 이야기하면 기능요구사항을 참고하여 각 기능과 사용 자원에 따라 모듈을 정리하고 해당 모듈에 컨트롤러들을 배치하는 형식이다.
이러한 방식은 한 번에 큰 단위의 초기작업을 진행하다보니 초기 작업 속도가 느려진다.
하지만 큰 틀이 잡혀 후속 작업이 금방금방 진행될 수 있다.
일반적으로 필자는 위와같이 큰 틀을 잡아놓고 후속 작업을 진행하는 탑바텀 방식을 선호한다. 큰 그림을 먼저 그리고 세부적인 디테일을 잡아가는게 필자의 스타일이기 때문이다.
그러나 카카오톡과 같은 서비스를 제공한다고 하면 너무너무 큰 대용량 작업이기 때문에 큰 틀을 잡는 것 자체가 너무 비효율적이어진다.
(카카오톡은 단순 메신저라고 생각할 수도 있지만 실제로 우리가 사용하는 카카오톡의 기능은 너무나도 많다. 예를들면 최근 화제가 되었던 인스타와 같은 피드 기능, 숏츠 기능, 선물 기능 등의 부가 기능이 정말 많다.)
그러한 경우에는 먼저 핵심적인 흐름을 잡아내어 작업을 하는 것이 편할 것 같다.
마무리
이상으로 필자가 사용하는 방식의 API 명세서 작성 방법에 대해 알아보았다.
항상 느끼는 바이지만 이 세상에는 완벽한 방법, 완벽한 무언가라는건 존재하지 않는 것 같다. 그래서 언제나 체크하고 의심하며 살아가는게 참 중요한 것 같다.
지금 내가 사용하는 방식이 과연 지금 상황에 맞는 방식인지. 이 방식이 최선인지를 생각하는게 완벽에 가장 가까워질 수 있는 방법인 것 같다.
오늘은 여기까지.
