API 명세서 작성

minsikk·2024년 12월 29일

api 명세서를 작성하려는 도중, 대충 작성하지 않고 api가 무엇인지, 명세서 작성은 어떻게 해야하는지 정확히 알고 작성하기 위해 이번 게시글을 작성하게 되었다.
kakao enterprise의 문서을 참고하여 작성하였다.

✏️API(Application Programming Interface)란?
= 서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체

그리고 API를 사용하기 위해 서버와 클라이언트 사이에 주고 받아야 할 약속이 존재한다. 메시지의 데이터 형식, 글자수 제한, 어떤 방식으로 데이터가 전달되어야 하는지, 요청에 대한 결과는 어떤 형식으로 확인할 수 있는지 등이 있다.

1. 개요(Overview)

= API 소개, 개발 배경, 비즈니스 목적 등과 함께 공통 요청(Request) 및 응답(Response) 형식, 공통 에러 타입 등 전반적인 API 소개와 동작 설명을 포함

API 소개 : 단순히 API에 대한 기능 설명 보다, API의 개발 배경, 비즈니스 목적, 장점 등을 포함해서 궁극적으로 외부의 독자들이 API를 좀 더 명확히 이해할 수 있도록!
공통 요청/응답 형식 : 한 서비스의 API는 통일된 방식으로 API 호출. 이때 API를 개발자가 어떤 방식으로 개발하느냐에 따라 문서의 구성이 달라짐
(ex.) Request
데이터 형식 'application/json'로 제한 OR 'application/x-www-form-urlencode'로 표현된 데이터를 허용
(ex.) Response
성공/실패 여부를 필드에서 성공인지 실패인지 설명 OR 상태코드 통해 제공
- 'application/x-www-form-urlencode'
  = HTTP 요청의 본문에 데이터를 URL 인코딩 방식으로 전송하는 미디어 타입. 주로 HTML 폼 데이터를 전송할 때 사용됨
  name=John&age=22&city=Seoul
  폼 데이터를 서버로 전송할 때 많이 사용되며, key=value 형식으로 인코딩하고 여러 데이터는 &로 구분한다. 복잡하거나 대량의 데이터에는 다른 미디어 타입을 사용하는 것이 더 효과적이다.
공통 에러 : API간 공통되는 에러 코드를 한 섹션에 모아두고 관리하기

2. 시작하기

특정 API를 호출하기 전, 인증 API 등의 선제적 API를 호출해야 하는 getting started 과정이 필요한 경우가 존재한다. 이처럼 API를 어떤 순서로 사용해야 하는지에 대한 가이드가 Swagger 이외의 별도의 문서에 제시하는 것이 바람직하다.

사전 작업
API 사용에 앞서 계정 등록 OR API Key 등록과 인증하는 등의 사전 작업이 필요할 수 O
(ex.) 사전에 인증키(App Key)를 어떻게 발급할 수 있고 어떤 용도로 사용되는지 상세히 설명되어야 함
API 사용 시퀀스 : API 사용 순서 작성

3. API 레퍼런스

= API 별 요청과 응답을 정리해 놓은 문서

요청(Request)
API 요청을 문서로 정리할 때, Request Syntax, Request Header, Request Element로 구분

▶️Request Syntax
= API의 형태, 구조에 대한 정의. API가 어떤 메서드를 사용하고, 요청 URL의 형태는 무엇인지, 코드 예제도 함께 제공.

▶️Request Header
= 요청에 대한 추가 정보를 담고 있음. 메시지의 총 길이, 형식 등 포함

▶️Request Element
= 해당 요청의 실제 메시지/내용 + API를 요청하기 위한 파라미터와 파라미터의 유형, 필수 여부와 설명, 제약 사항 등