[1人1P] 4-2. 백엔드 개발 (API 명세 작성)

이번 포스트에서는 저번 NestJS에 대한 개괄적인 설명 이후에 실제 개발로 넘어가는 첫 단계이다.

API 명세서란?

API 명세서는 백엔드를 작성하기 전에 API의 엔드포인트, 요청 형식, 응답 형식 등을 미리 정의해둔 문서이다. API 명세서를 작성하는 대표적인 이유는 타 부서(기획, 프론트엔드 등)과 협업하기 위해 주로 작성하며, 백엔드 작성 이전에 기능을 미리 정의해봄으로써 구조가 잘 잡힌 백엔드를 개발하기 위해 작성하기도 한다.

API 명세서를 작성하는 방법

API 명세서를 작성하는 규격이 존재하는 것은 아니다. 하지만 주로 협업을 위해 명세서를 제작하는 만큼 프로젝트에서 사용하는 API 명세서의 규격은 정해놓을 필요가 있다. 필자는 API 명세서를 작성하기 위해 Apidog라는 서비스를 사용할 것이다.

Apidog에서는 API 명세서를 간단하게 생성할 수 있을 뿐만 아니라 프로덕션 서버와 개발 서버에 실제 응답 요청을 보낼 수도 있고, 백엔드 완성 이전에 프론트엔드 개발을 위한 더미 API 응답 기능도 제공한다. 이로서 API 명세서를 작성하고 협업하는 과정에서의 낭비되는 시간을 줄여주는 장점이 있다.

결론부터

앞선 포스트에서 다뤘던 기능 요구사항을 토대로 필요한 기능을 먼저 정리했다. API의 큰 틀부터 잡아가기 위해 Auth, Task, Score, Reflection 엔드포인트 그룹을 먼저 생성했다. 위 사진은 Auth 기능의 엔드포인트들이다.

로그인(GET-auth/login), 로그인 콜백(POST-auth/login/callback),리프레시(POST-auth/refresh) 등의 엔드포인트가 정의되어 있는 것을 확인할 수 있다. 참고로 본 서비스에서는 구글의 OAuth를 이용한 로그인 방법을 제공할 것이기 때문에 콜백을 위한 엔드포인트가 별도로 존재하는 것이다.

위 사진은 auth/login/callback의 엔드포인트에 대한 API 명세의 모습이다. 간단히 설명해보자면 POST Body로 구글에서 제공한 idToken을 전송하면, 서버에서 로그인 처리 후 JWT 토큰으로 된 access_token과 refresh_token을 발급해서 응답한다.

응답의 예시는 오른쪽에 보이는 것 처럼 JSON 형식으로 응답한다. 이처럼 단일 엔드포인트에 대한 경로, 요청 형식, 응답 형식 등을 미리 정의하는 것이다. 추가로 API 처리 과정 중 성공했을 경우, 실패했을 경우, 그리고 다양한 오류의 종류들 또한 미리 정의한다.

명세서를 작성하고 나서

명세서가 완성되면 백엔드 개발자는 본격적인 백엔드 개발을 시작해야 할 것이다. 이때 원활한 협업을 위해 미리 작성한 API 명세서를 꼭 준수하여 개발해야 한다.

이번 프로젝트는 필자가 백엔드와 프론트엔드를 모두 구현하는 1인1프로젝트이기 때문에 협업에 대한 순서 제약을 받지 않고 함께 개발을 진행했다.

프로젝트 상황에 따라서 백엔드 개발이 완료되기 까지 프론트엔드 개발이 진행되기 어려운 경우도 있다. 지금처럼 기존의 서비스가 없어 프론트엔드 개발자가 테스트하며 진행할 충분한 리소스가 없는 경우가 해당 사례에 적합한 것 같다.

마지막

API 명세 작성을 하나의 포스트로 적기엔 양이 굉장히 적은 것 같다. 하지만 단순히 백엔드 개발의 아주 작은 한 단계로 다른 포스트에 묻어가기엔 굉장히 중요한 단계이기 때문에 별도의 포스트로 적는다.