[API] API 명세서 작성하는 방법

API 명세서란?

 

API 명세 가이드라인

• API 개요: API를 간단하게 설명하는 섹션. API가 어떤 용도로 만들어졌는지, 어떤 유형의 API인지, 어떤 요청 방식을 사용하는지 등을 설명한다.
• 엔드포인트(endpoint) 설명: API에 대한 각 엔드포인트에 대한 설명. 각 엔드포인트는 API의 특정 동작을 수행하며, 일반적으로 HTTP 메소드(GET, POST, PUT, DELETE 등)를 사용하여 호출한다. 각 엔드포인트의 URL과 함께 해당 엔드포인트에서 수행되는 동작을 설명한다.
• 매개변수(Parameter)와 요청 바디(Request Body) 설명: API 호출 시 전달되는 매개변수와 요청 바디에 대한 설명을 포함한다. 각 매개변수에 대한 설명, 데이터 타입, 기본값 등을 명시한다.
• 응답(Response) 설명: API의 응답에 대한 설명을 포함한다. 응답 코드와 함께 예상되는 응답 데이터에 대한 정보를 제공한다.
• 예제(API examples): 각 API 호출에 대한 예제를 제공한다. 이 예제는 API 사용자가 API 호출을 어떻게 수행해야 하는지를 이해하는 데 도움이 된다.
• 에러(Error) 처리 설명: API 호출 중 발생할 수 있는 예외나 오류에 대한 처리 방법을 설명한다.
• 인증(Authentication)과 권한 부여(Authorization) 설명: API에 대한 인증 및 권한 부여 방법을 설명한다.
• 자원(Resource) 모델 설명: API가 사용하는 자원 모델에 대한 설명을 제공한다. 이 섹션에서는 각 자원이 어떻게 표현되는지, 자원에 대한 식별자는 무엇인지, 자원의 상태와 상태 전이에 대한 정보를 제공한다.

 

개요로 API에 대해 설명하고, 동작이 일어나는 엔드포인트를 설명하고, 매개변수(인자)를 어떤 걸 받아야 하는지에 대해 명시하고, 응답이 어떻게 오는지, 어떤 식으로 API를 보내면 되는지, 에러가 난다면 어떻게 처리해야 하는지, 어떤 자원을 사용하는지에 관해 설명한다.

 

API 명세 예제

Posts API

Request

curl -X POST https://{SERVER_URL}/api/posts \
  -H "Content-Type: application/json" \
  -d '{ \
        "content": "내용" \
      }'

 

 

메서드요청 URL

POST	http://{SERVER_URL}/api/posts

 

Request Header

Content-Type	String	필수	application/json

 

Request Elements

content	String	필수	내용

Response

{
  "id" : 1
}

Response Elements

id

Integer

필수

포스트 고유 번호

---

포스트 목록 조회

Request

curl -X GET https://{SERVER_URL}/api/posts?page=1&size=1 \
  -H "token: {API_KEY}"

 

메서드요청 URL

GET	http://{SERVER_URL}/api/posts

 

Request Header

toekn

String

필수

인증 키

 

Request Elements

page	Integer	선택	페이지 번호
size	Integer	선택	한 페이지에 표시할 포스트 개수

 

Response

{
  "page": 1,
  "size": 1,
  "totalPage": 150,
  "totalCount": 1496,
  "data": [
  	{
      "id": 1,
      "title": "제목1",
      "content": "내용1",
    },
    {
      "id": 2,
      "title": "제목2",
      "content": "내용2",
    },
    {
      "id": 3,
      "title": "제목3",
      "content": "내용3",
    }
  ]
}

Response Elements

page	Integer	필수	페이지 번호
size	Integer	필수	한 페이지에 표시할 포스트 개수
totalPage	Integer	필수	전체 페이지
totalCount	Integer	필수	전체 포스트
data	Integer	필수	포스트 목록
id	Integer	필수	포스트 고유 번호
title	Integer	필수	포스트 제목
content	Integer	필수	포스트 내용

 

 

오늘은 API 명세서 작성하는 방법을 알아보았다.