강남언니 "프론트엔드 개발자가 API를 설계하는 이유"를 읽고 -> 웹채팅 API 문서 회고록

글의 주제 : IDL을 이용한 효율적인 인터페이스 관리 전략

https://blog.gangnamunni.com/post/saas-why-do-frontend-developers-design-api/

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

 이 글에서 인상 깊었던 점은 "프론트엔드가 주도하여 인터페이스를 설계하는" 개발의 이점을 소개해주었다는 것이다. 이를 통해 프론트엔드 개발자의 업무 블락커 발생을 줄이고 API가 백엔드 개발자에게 종속되는 것을 막을 수 있음을 알려주었다. 이 글을 읽으며 지난 웹 채팅 프로젝트가 생각이 났다. 이 프로젝트에서 나는 프론트엔드 주도 인터페이스 설계를 경험해봤다.

 

 보통 API 설계를 백엔드가 주도하기 때문에 API 명세 및 문서 관리 또한 백엔드의 책임으로 많이 생각하는 것 같다. 나 또한 이전의 웹 프로젝트에서 채팅 백엔드 서버를 설계하며 API 문서를 만들고 관리하는데 많은 시간과 어려움을 겪었다.

 그 가운데서 가장 비 효율적이었던 것은, 프론트엔드 개발자 분이 개발을 하려면 호출할 API의 인터페이스를 알아야하는데, 백엔드 메서드가 아직 만들어지지 않은 경우 작업을 하지 못하는 경우가 있다는 것이었다. DB 설계도, 백엔드 서버 구축도, 심지어는 사용하는 언어(TS)와 프레임 워크(NestJS)까지 모든 게 다 처음이었던 나는 typeORM을 사용해 릴레이션 된 테이블의 데이터 삭제를 하기 위해 고전 중이었고, 프론트 엔드 개발자 분에게 항상 작업량을 따라 잡히기 일쑤였다. 따라서 아직 만들어 지지 않은 API 에 대해서도 프론트엔드와 미리 이야기를 나누는 일이 많아졌고, 자연히 프론트엔드 쪽에서 인터페이스설계를 이끌게 되었다.

 그 결과 오히려 백엔드에서 최대한 필요한 정보만을 가공해 프론트엔드에게 보낼 수 있었고, 이 때문에 나는 맵핑 클래스를 만들고 객체배열 등에 모두 적용해야 했으나, DB 데이터를 바로 전달하지 않아  보안적으로도 좋았다고 생각한다.

 

아래는 프로젝트 초기, google docs를 활용하여 백엔드 서버 구현 담당인 내가 주도해 만든 API 문서 이다.

다음은 프로젝트가 진행됨에 따라 프론트엔드에서 API 인터페이스를 주도해서 설계한 당시 기록이다.

초반에는 백엔드인 내가 먼저 google docs에 구현 및 테스트를 마친 API를 작성하고 프론트엔드에게 전달 했으나, 계속해서 프론트 엔드쪽에서 API 설계를 기다리는 식이 되어 이후엔 프론트엔드 쪽에서 설계하는 메서드 + 백엔드에서 만든 메서드를 API 표 문서에 최종본으로 정리했다.

 이 과정에서 프론트엔드와 실시간으로 피드백 할일이 많았고 이 가운데 다음과 같이 notion에 요청사항을 남기며 진행했다.

 곧 시작할 웹 프로젝트에서도 프론트엔드와 많은 피드백을 해야할 것으로 예상된다. 위 강남언니 백엔드 개발자 분의 Technical Writing 에서 소개한 IDL를 활용한 프론트엔드 주도 인터페이스 관리 전략을 적용하여 프론트 엔드쪽의 블럭커를  방지하고 프론트와 백엔드 간의 상호 이해가 깊어질 수 있게 노력해야겠다.