TIL - backend API 명세서 작성 가이드

API 명세서 만들기

1) API 명세서를 작성하는 이유

• API 명세서를 작성하지 않으면 사용자는 어떤 정보를 어떤 방식으로 요청해야하는지, 어떤 정보를 전달 받을 수 있을지, 어떤 형식으로 데이터가 넘어오는지 알 수 없다.

2) API 레퍼런스

• API의 약속은 보통 요청 방식, 요청 파라미터 유형, 파라미터의 필수 여부 등을 의미한다. 개발자는 이 약속들을 확인하고 용도에 맞게 코드를 작성해야 한다. API 별 요청과 응답을 정리해놓은 문서가 API 레퍼런스이다. API 레퍼런스는 대게 Request 와 Response로 구성된다.

요청(Request)
API 요청을 제대로 하기 위해서는 특정 항목들을 일정 포맷에 따라 호출해야 한다. API 요청을 문서로 정리할 때 카카오 엔터프라이즈 팀에서는 Request Syntax, Request Header, Request Elemnet로 구분한다.

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

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

-Request Element
Request Element는 해당 요청의 실제 메시지/내용이다. API를 요청하기 위한 파라미터와 파라미터의 유형, 필수 여부와 설명, 제약 사항 등이 제공되어야 한다. GET 메서드의 Element가 없는 요청처럼 드물게 Element의 요청이 없는 경우도 있다.