[BackEnd] API 명세서 작성 가이드 라인 | 작성 예시

프로젝트에서 API 명세서와 ERD 설계를 맡았다. API 명세서를 작성해본 적이 없어서 최대한 공식적인 자료를 바탕으로 찾아보다가 사막의 오아시스같은 글을 발견해서 정리하고 두고두고 보려고 한다. 이번 프로젝트에서 활용을 당연히 하겠지만 앞으로도 정말 큰 도움이 될 것같다..😍 

API는 '서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체'이다.
API 명세서는 서버와 클라이언트간 특정 기술을 사용하기 위한 약속이다.
 

API 문서화에 들어가야할 내용

1) 개요

기술 문서의 서론은 독자들에게 본문의 요약, 작성 배경, 관련 개념을 설명해준다. 즉, 독자들을 위한 '가이드'이다. API 문서에도 서론의 역할을 하는 개요(Overview)가 필요하다.
 
API 소개
단순히 API에 대한 기능 설명을 하는 것 보다는 API의 개발 배경, 비즈니스 목적, 장점 등을 포함하여 외부 개발자가 API를 명확히 이해할 수 있도록 한다.
 
공통 요청/응답 형식
일반적으로 한 서비스의 API는 통일된 방식으로 API를 호출하며, 이때 API를 개발자가 어떤 방식으로 개발했느냐에 따라 문서의 구성이 달라진다. 예를 들어 API 요청을 할 때 사용하는 데이터 형식을 'app/json'으로 제한하거나, 'app/x-www-form-urlencode'로 표현된 데이터를 허용하는 개발자도 있다. 
응답도 마찬가지로 어떤 개발자는 성공/실패 여부를 sucess 필드에서 성공인지 실패인지 설명하는 반면, 다른 개발자는 상태코드를 통해 제공한다. 이런 점들이 API 문서에 정확하게 반영되어야 한다. 
 
공통 에러
만약 API 간 공통되는 에러 코드가 존재한다면, 문서의 한 섹션에 에러 코드를 모아두고 관리하는 것이 효율적이다.
엔터프라이저에서 추천하는 방식: 문서의 한 섹션(개요 문서)에 공통 에러를 제공하고, 각 API에 공통 에러 테이블을 링크로 연결한다.
 

2) 시작하기

사전 작업
고객사에서 API 문서를 요청했을 때 Swagger 등의 링크나 API 명세서만 제시하는 경우가 대표적이지만,사용 순서를 문서화 할 수 있는 공간에 제약이 있기 때문에 별개로 별도의 문서에 API의 사용 순서를 설명하는 시작 가이드를 제작하는 것이 바람직하다.
 
API 사용 시퀀스
예를 들면 특정 멤버 조회 > 해당 멤버와의 채팅방 생성 > 메시지 전송
이러한 API 사용 시퀀스가 존재한다면 넘버링 형식으로 시퀀스를 정리해야 한다.
 

3) API 레퍼런스

API의 약속은 보통 요청 방식, 요청 파라미터 유형, 파라미터의 필수 여부 등을 의미한다. 개발자는 이 약속들을 확인하고 용도에 맞게 코드를 작성해야 한다. API 별 요청과 응답을 정리해놓은 문서가 API 레퍼런스이다. API 레퍼런스는 대게 요청(Request)과 응답(Response)로 구성된다.
 
요청(Request)
API 요청을 제대로 하기 위해서는 특정 항목들을 일정 포맷에 따라 호출해야 한다. API 요청을 문서로 정리할 때 카카오 엔터프라이즈 팀에서는 Request Syntax, Request Header, Request Element로 구분한다.

 
♦︎ Request Syntax
Request Syntax는 API의 형태, 구조에 대한 정의다. API가 어떤 메서드를 사용하는지, 요청 url의 형태는 무엇인지, 그리고 코드 예제가 함께 제공되어야 한다.
 

 
♦︎ Request Header
Request Header는 요청에 대한 추가 정보를 담고 있는 부분이다. 예를 들어 메시지의 총 길이, 형식 등이다. 앞에서 발급 받은 인증을 위한 정보를 Header에 작성하기도 한다.

 
♦︎ Request Element
Request Element는 해당 요청의 실제 메시지/내용이다. API를 요청하기 위한 파라미터와 파라미터의 유형, 필수 여부와 설명, 제약 사항 등이 제공되어야 한다. GET 메서드의 Element가 없는 요청처럼 드물게 Element의 요청이 없는 경우도 있다.
 
이런식으로 상세한 내용은 Excel에 보기좋게 정리하는게 좋겠다.

 

---

적용한 API 명세서

 
노션을 활용하였고, 기능/HTTP method/API path 등등 중요한 정보들을 컬럼으로 지정하여 작성하였다.
 

 

 

API의 상세 내용은 다음과 같다.

 
 
요청 헤더와 요청값, 에러값을 JSON으로 정의하였다. (해당 예제는 GET 요청이기에 Request 값에 대한 정의가 없다.)

 

 

이 작업은 프론트와의 협업을 위해 굉장히 중요한 작업이다.
각각의 기능에 대해 프론트-백 개발자들은 이 명세서로 구현을 하기 때문이다. 

이 작업을 놓쳐서 헤매는 개발팀을 봤다,,, 예를 들어 백에서는 api 주소를 /api/resources 이런식으로 썼는데 프론트에서는 /api/resource 이런식으로 정의를 해서 요청과 응답이 안되는 경우, API 명세서를 처음부터 잘 작성하고 작업을 하면 이런 일은 없을 텐데 말이다. 서로 구두를 통해 API를 정의하면 괜한 곳에 시간을 많이 소비하게되니, 이 과정만큼은 꼭 진행하는 것이 좋다.
 
 
공통 응답/요청에 대해 정의하였고, 공통 에러 또한 엑셀 시트를 통해 관리하였다.

공통 응답/요청 방식, JSON 정의

1. API 요청 형식은 *‘application/json’*으로 제한합니다. 이때 application 대신에 app으로 줄여서 씁니다.
2. 성공/실패 여부는 HTTP 상태코드를 통해 제공합니다. 상태 코드는 다음과 같습니다.

 200번대 : 성공

300번대 : 리다이렉트

400번대 : 클라이언트 오류(request error)

500번대 : 서버 오류

 
 

공통 에러

 
 

JSON 형식

{
	"code" : 
	"message":
	"result" : 
}

 

 

---

첫 프로젝트를 진행하면서 ERD와 API 명세는 한번 제대로 도맡아보고 싶었다. 와이어프레임을 보면서 기능 별로 api 경계를 나누고, 요청과 응답에 대해 직접 정의했다. 또 다른 기업에서는 명세를 어떻게 쓰는지 이런저런 자료를 보면서, 필수적인 것들을 골라서 작성해보았다. Swagger같은 좋은 API 명세 툴도 있지만 직접적으로 작성하는 경험을 통해 깊이있는 학습을 했고, 프로젝트에 많은 기여를 할 수 있었다.