| 목차 |
| 1. API 명세서 설명 |
| 2. API 명세서 작성하기 |
| 3. 효율적인 API 명세서 작성 및 관리 방안 |
API(애플리케이션 프로그래밍 인터페이스) 명세서 설명
API명세서는 쉽게 말해 내가 만든 백엔드 서버의 사용 설명서입니다.
저는 팀 프로젝트이기 때문에 노션 에서 API명세서를 팀원들가 함께 작성했습니다
API명세서의 구성을 보면 왼쪽부터 해당기능의 담당자 / 진행상황 / HTTP메서드(get, post등) / 기능이름 / URL / 리퀘스트헤더 / 리스폰스헤더 / 리퀘스트 / 리스폰스 로 구성되어있습니다.
예를들어 워크스페이스 조회 기능같은 경우에는 로그인한 회원만 접근할 수 있는 기능 이기 때문에
해당 기능의 리퀘스트 헤드에는 토큰값을 필요로 한다는 의미에서 Authorization:Bearer 라고 명시를 했습니다
API명세서 작성하기
저희는 위 예시 사진과 같이 먼저 HTTP 메서드와 기능명들을 모두 작성한 후, 각 기능에 대한 세부 API 명세서를 작성하였습니다.
해당 기능들에 대해 어떤 리퀘스트 값을 받아야 하는지와 어떤 리스폰스를 반환할지를 명확히 정의하였습니다. 이를 통해 각 API의 입력과 출력을 구체적으로 규정하여, 개발자들이 구현 시 혼동 없이 작업할 수 있도록 하였습니다.
이번 프로젝트에서 필요한 기능들을 정리한 결과, 아래와 같은 표로 정리되었습니다.
| 로그인 |
| 회원가입 |
| 이메일 인증 |
| 사용자 정보 수정 |
| 회원탈퇴 |
| 워크스페이스 생성 |
| 워크 스페이스 조회 |
| 워크 스페이스 상세 조회 |
| 워크스페이스 멤버 초대 |
| 보드 조회 |
| 보드 상세 조회 |
| 보드 생성 |
| 보드 수정 |
| 보드 삭제 |
| 리스트 조회 |
| 리스트 상세 조회 |
| 리스트 생성 |
| 리스트 수정 |
| 리스트 삭제 |
| 리스트 순서 이동 |
| 카드 조회 |
| 카드 상세조회 |
| 카드 생성 |
| 카드 수정 |
| 카드 삭제 |
| 카드 이동 |
| 댓글 생성 |
| 댓글 수정 |
| 댓글 삭제 |
| 카드 마감일 관리 |
| 파일 첨부 |
| 파일 다운로드 |
| 체크리스트 생성 |
| 체크리스트 수정 |
| 체크리스트 삭제 |
| 아이템 생성 |
| 아이템 수정 |
| 아이템 삭제 |
효율적인 API 명세서 작성 및 관리 방안
전체 기능에 대한 API 명세서를 작성하였으나, 한 사람이 모든 명세서를 작성하기에는 양이 많아 비효율적이라 판단하여, 각 기능별로 담당자를 지정하고, 각자가 자신이 맡은 기능에 대한 API 명세서를 작성하도록 하였습니다.
API 명세서를 미리 작성하면, 요구사항이 명확해지고 개발 일관성이 유지됩니다. 프론트엔드와 백엔드가 동시에 작업할 수 있으며, 문서화와 테스트가 용이해집니다. 시스템 간 호환성 문제를 미리 파악하고, 초기 단계에서 문제를 발견할 수 있습니다. 또한, 팀 간 커뮤니케이션이 개선되고, 유지보수도 용이해집니다.