[Project] API 명세서

API 명세서

- API: 서버와 클라이언트가 데이터를 주고 받을 수 있도록 도움을 주는 매개체

- API 명세서: 어떤 용도로 만들어졌는지, 어떤 유형의 API 인지 어떤 요청 방식을 사용하는지 설명

- endpoint 설명: endpoint는 API의 특정 동작을 수행. URL과 함께 해당 엔트포인트에서 수행되는 동작을 설명

- parameter와 request body 설명: API 호출시 전달되는 매개변수와 요청바디에 대한 설명을 포함. 매개변수에 대한 설명, 데이터 타입, 기본값을 명시

- response 설명: API의 응답에 대한 설명을 포함. 응답 코드와 함께 예상되는 응답 데이터에 대한 정보를 제공

- API examples: 각 API 호출에 대한 예제를 제공. API 사용자가 API 호출을 어떻게 수행해야 하는지 이해에 도움

- error 처리 설명: API 호출 중 발생할 수 있는 예외나 오류에 대한 처리 방법 설명

- authentication/authorization 설명: API에 대한 인증 및 권한 부여 방법 설명

- resource 모델 설명: API 가 사용하는 자원 모델에 대한 설명 제공. 각 자원이 어떻게 표현되는지, 자원에 대한 식별자는 무엇인지, 자원의 상태와 상태 전이에 대한 정보를 제공

 

API 명세서 작성법

1. method, url, request, response, description 포함하여 작성

- method: HTTP Method를 의미

- url: 인터넷의 자원을 식별할 수 있는 문자열/주소

- request body: API에 제공할 데이터. POST, PUT일 경우 작성

- response body: API가 생성하는 응답 데이터. JSON/XML 형식

- description: 상세 설명

+) status: 반환되는 코드와 설명

+) params: query params, path params

+) headers: content-type, authorization

 

참고자료

- [kakao enterprise] API 문서 돌아보기