API 문서, 어디부터 봐야 할까?

API 문서는 클라이언트와 서버가 어떤 요청과 응답을 주고받을지 정리한 약속 문서다.

처음 API 문서를 보면 Method, Path, Parameter, Request Body, Response, Status Code 같은 정보가 한꺼번에 보여 복잡하게 느껴질 수 있다.

하지만 정해진 순서대로 읽으면 생각보다 어렵지 않다.

보통 다음과 같은 순서로 확인하면 된다.

1. API의 목적
2. HTTP Method
3. Path
4. 인증 필요 여부
5. Path Parameter
6. Query Parameter
7. Request Body
8. 성공 응답
9. 실패 응답

이 글에서는 간단한 예제를 통해 API 문서를 어떤 순서로 읽으면 되는지 정리해보려고 한다.

API 문서는 어떤 문서일까?

API 문서는 단순히 호출할 URL만 적어놓은 문서가 아니다.

다음과 같은 내용을 함께 설명한다.

어떤 기능을 제공하는 API인지
어떤 주소로 요청해야 하는지
어떤 값을 전달해야 하는지
성공하면 어떤 응답이 오는지
실패하면 어떤 상태 코드와 메시지가 오는지

즉, API 문서를 읽는다는 것은 단순히 URL을 찾는 일이 아니다.

이 요청이 어떤 목적을 가지고 있고, 무엇을 보내야 하며, 어떤 결과를 기대할 수 있는지를 확인하는 일이다.

OpenAPI 문서는 어떻게 구성될까?

OpenAPI 문서에서는 API의 경로를 paths 아래에 정의한다.

각 Path 아래에는 get, post, put, patch, delete 같은 HTTP Method별 동작이 들어간다.

예를 들면 다음과 같은 구조다.

paths:
  /users/{id}:
    get:
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: User found
        "404":
          description: User not found

위 문서에는 다음 정보가 들어 있다.

어떤 Path로 요청하는지
어떤 HTTP Method를 사용하는지
어떤 Parameter를 받는지
어떤 Response가 발생할 수 있는지

Request Body가 필요한 API라면 requestBody 항목도 추가될 수 있다.

API 문서는 결국 하나의 요청이 어떤 입력을 받고, 어떤 결과를 반환하는지 표현한 문서라고 볼 수 있다.

처음에 헷갈리는 부분

처음 API 문서를 보면 다음과 같은 용어들이 한꺼번에 나온다.

GET
/users/{id}
Path Parameter
Query Parameter
Request Body
Response Body
Status Code
Header

처음에는 전부 비슷하게 느껴질 수 있다.

특히 다음과 같은 부분에서 많이 헷갈린다.

Path Parameter와 Query Parameter는 무엇이 다를까?
GET 요청에도 Body를 보내야 할까?
Response 예시는 성공한 경우만 보면 될까?
Status Code는 왜 따로 확인해야 할까?

이런 정보들을 한꺼번에 이해하려고 하면 어렵다.

API 문서는 위에서 아래로 빠르게 훑기보다, 항목별로 나눠서 확인하는 편이 좋다.

API 문서는 주문서 양식과 비슷하다

API 문서는 식당 메뉴판보다 주문서 양식에 가깝다.

메뉴판은 어떤 음식을 주문할 수 있는지를 보여준다.

하지만 주문서 양식은 조금 더 구체적이다.

어떤 메뉴를 주문할 수 있는지
수량은 어디에 적는지
맵기 선택은 필수인지
추가 옵션은 어떻게 선택하는지
주문이 성공하면 무엇을 받는지
주문이 실패하면 어떤 안내가 나오는지

API 문서도 비슷하다.

어떤 API를 호출할 수 있는지
어떤 값을 Path에 넣어야 하는지
어떤 값을 Query String으로 보내야 하는지
Body에는 어떤 JSON을 보내야 하는지
성공하면 어떤 JSON이 반환되는지
실패하면 어떤 상태 코드가 반환되는지

그래서 API 문서를 읽을 때는 “주소가 무엇이지?”에서 끝내면 안 된다.

“어떤 모양으로 요청해야 하지?”와 “어떤 응답이 올 수 있지?”까지 확인해야 한다.

작은 예제로 읽어보기

다음과 같은 API 문서가 있다고 해보자.

GET /users/{id}

Description:
사용자 상세 정보를 조회한다.

Path Parameter:
id
- 설명: 사용자 ID
- 타입: Long
- 필수 여부: 필수

Query Parameter:
includePosts
- 설명: 작성 글 포함 여부
- 타입: boolean
- 필수 여부: 선택
- 기본값: false

200 OK Response:
{
  "id": 1,
  "name": "junior",
  "posts": [
    {
      "id": 10,
      "title": "첫 번째 글"
    }
  ]
}

404 Not Found Response:
{
  "code": "USER_NOT_FOUND",
  "message": "사용자를 찾을 수 없습니다."
}

이 문서를 순서대로 읽어보자.

1. API의 목적 확인하기

먼저 Description을 확인한다.

사용자 상세 정보를 조회한다.

이 API는 특정 사용자의 상세 정보를 조회하는 API다.

API 이름이나 URL만 보는 것보다 Description을 먼저 확인하면 이 API가 어떤 용도로 만들어졌는지 이해하기 쉽다.

2. HTTP Method 확인하기

다음으로 Method를 확인한다.

GET

GET은 리소스를 조회할 때 주로 사용하는 Method다.

HTTP Method마다 의미가 다르기 때문에 단순히 URL만 보는 것이 아니라, 이 요청이 조회인지 생성인지 수정인지 삭제인지 함께 확인해야 한다.

일반적으로는 다음과 같이 구분한다.

GET: 조회
POST: 데이터 전달 및 처리, 생성
PUT: 전체 수정
PATCH: 일부 수정
DELETE: 삭제

실제 API가 어떤 의미로 설계되었는지는 문서의 Description과 함께 확인해야 한다.

3. Path 확인하기

다음으로 요청할 Path를 본다.

/users/{id}

{id}처럼 중괄호로 표시된 값은 실제 값을 넣어야 하는 Path Parameter다.

예를 들어 ID가 1인 사용자를 조회한다면 다음과 같이 호출한다.

GET /users/1

API 문서에서는 보통 Path Parameter라고 부른다.

Spring에서는 이 값을 @PathVariable을 사용해 받는다.

4. Query Parameter 확인하기

이 API에는 includePosts라는 Query Parameter도 있다.

includePosts

Query Parameter는 URL 뒤에 ?를 붙여 전달한다.

작성 글을 함께 받고 싶다면 다음과 같이 호출할 수 있다.

GET /users/1?includePosts=true

Query Parameter가 여러 개라면 &로 연결한다.

GET /users?page=1&size=20

문서를 읽을 때는 Parameter 이름만 보는 것이 아니라 다음 내용도 함께 확인해야 한다.

타입
필수 여부
기본값
허용 가능한 값

이 예제에서 includePosts는 선택값이며, 전달하지 않으면 기본값으로 false가 사용된다.

따라서 다음 요청도 가능하다.

GET /users/1

5. Request Body 확인하기

이 API는 GET 요청이므로 별도의 Request Body가 없다.

조회 조건은 Path Parameter나 Query Parameter로 전달한다.

GET 요청에는 일반적으로 Request Body를 사용하지 않는다.

GET Body의 의미는 명확하게 정의되어 있지 않고, 일부 서버나 중간 장비에서 요청을 정상적으로 처리하지 못할 수도 있다.

특별한 이유가 없다면 GET 요청의 조회 조건은 Path나 Query Parameter로 전달하는 편이 좋다.

반면 POST, PUT, PATCH 요청은 Body에 JSON을 담아 전송하는 경우가 많다.

POST /users
Content-Type: application/json

{
  "name": "junior",
  "email": "junior@example.com"
}

Request Body를 확인할 때는 다음 항목을 살펴봐야 한다.

필수 필드는 무엇인지
선택 필드는 무엇인지
각 필드의 타입은 무엇인지
문자열 길이나 숫자 범위 제한이 있는지
null을 허용하는지

6. 성공 응답 확인하기

요청이 성공하면 200 OK 상태 코드와 함께 사용자 정보가 반환된다.

{
  "id": 1,
  "name": "junior",
  "posts": [
    {
      "id": 10,
      "title": "첫 번째 글"
    }
  ]
}

Response를 볼 때는 JSON 모양만 확인하면 안 된다.

해당 Response가 어떤 Status Code에서 반환되는지도 함께 봐야 한다.

예를 들어 동일한 JSON 형태처럼 보여도 상태 코드가 200인지 400인지에 따라 클라이언트에서 처리해야 하는 방식이 달라진다.

또한 응답 필드도 함께 확인하는 것이 좋다.

각 필드의 타입은 무엇인지
항상 반환되는 필드인지
조건에 따라 생략될 수 있는지
null이 올 수 있는지
배열이 비어 있을 수 있는지

이 예제에서는 includePosts=true인 경우에만 posts가 포함되는지, false여도 빈 배열로 오는지, 아니면 필드 자체가 생략되는지도 확인할 필요가 있다.

7. 실패 응답 확인하기

ID에 해당하는 사용자가 없다면 404 Not Found가 반환될 수 있다.

{
  "code": "USER_NOT_FOUND",
  "message": "사용자를 찾을 수 없습니다."
}

여기서 중요한 점은 성공 응답만 보면 부족하다는 것이다.

실무에서는 실패 응답을 알아야 프론트엔드에서도 상황에 맞는 화면을 보여줄 수 있다.

예를 들어 사용자를 찾을 수 없다면 단순히 화면이 멈추는 것이 아니라 다음과 같은 처리를 할 수 있다.

사용자를 찾을 수 없다는 안내 표시
목록 화면으로 이동
재시도 버튼 제공
잘못된 주소라는 메시지 표시

404 외에도 API에는 다양한 실패 응답이 정의될 수 있다.

400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
500 Internal Server Error

따라서 예제에 나온 응답 하나만 보는 것이 아니라, 문서에 정의된 주요 Status Code를 모두 확인해야 한다.

Spring Boot 코드와 연결해보기

위 API는 Spring Boot에서 대략 다음과 같이 구현할 수 있다.

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public UserResponse getUser(
            @PathVariable Long id,
            @RequestParam(defaultValue = "false") boolean includePosts
    ) {
        return userService.getUser(id, includePosts);
    }
}

API 문서와 코드를 연결해보면 다음과 같다.

GET
-> @GetMapping

/users/{id}
-> @RequestMapping("/users") + @GetMapping("/{id}")

Path Parameter id
-> @PathVariable Long id

Query Parameter includePosts
-> @RequestParam boolean includePosts

Response Body
-> UserResponse

API 문서가 낯설게 느껴질 때는 Controller 코드와 나란히 놓고 보면 훨씬 이해하기 쉽다.

문서에 적힌 각 항목이 실제 코드의 어떤 부분과 연결되는지 확인할 수 있기 때문이다.

Path Parameter와 Query Parameter의 차이

Path Parameter와 Query Parameter는 처음 API 문서를 볼 때 가장 자주 헷갈리는 부분이다.

Path Parameter는 특정 자원을 식별할 때 주로 사용한다.

GET /users/1
GET /posts/10
GET /orders/100

위 요청에서 1, 10, 100은 조회하려는 자원을 구분하는 값이다.

Query Parameter는 조회 조건이나 옵션을 전달할 때 자주 사용한다.

GET /users?page=1&size=20
GET /posts?keyword=spring
GET /orders?status=PAID

간단히 정리하면 다음과 같다.

Path Parameter
-> 어떤 자원을 조회할 것인지 식별한다.

Query Parameter
-> 어떤 조건이나 옵션으로 조회할 것인지 지정한다.

다만 모든 API가 이 원칙을 완전히 동일하게 따르는 것은 아니다.

실제 요청 형식은 해당 API 문서를 기준으로 확인해야 한다.

인증과 Header도 확인해야 한다

인증이 필요한 API라면 Header 정보도 확인해야 한다.

예를 들어 Bearer Token을 사용하는 API라면 다음과 같은 Header가 필요할 수 있다.

Authorization: Bearer {accessToken}

JSON Body를 전송하는 요청이라면 다음 Header도 자주 사용한다.

Content-Type: application/json

다만 모든 Header를 직접 작성해야 하는 것은 아니다.

Swagger UI, HTTP Client, 공통 인터셉터 또는 프론트엔드의 API 모듈에서 자동으로 추가하는 Header도 있을 수 있다.

따라서 문서에서는 다음 내용을 확인하는 것이 좋다.

인증이 필요한 API인지
어떤 인증 방식을 사용하는지
Token을 어느 Header에 넣는지
Content-Type은 무엇인지
추가로 필요한 Header가 있는지

Status Code의 의미도 확인해야 한다

Status Code는 요청 처리 결과를 나타낸다.

대표적인 Status Code는 다음과 같다.

200 OK
요청이 정상적으로 처리됨

201 Created
리소스가 정상적으로 생성됨

204 No Content
요청은 성공했지만 반환할 Body가 없음

400 Bad Request
요청 값이나 형식이 잘못됨

401 Unauthorized
인증 정보가 없거나 유효하지 않음

403 Forbidden
인증은 되었지만 해당 요청을 수행할 권한이 없음

404 Not Found
요청한 리소스를 찾을 수 없음

409 Conflict
현재 리소스 상태와 요청이 충돌함

500 Internal Server Error
서버 내부 오류가 발생함

일반적으로 인증되지 않은 요청은 401, 인증은 되었지만 권한이 부족한 요청은 403으로 구분한다.

다만 실제 서비스마다 응답 정책이 다를 수 있으므로, API 문서에 정의된 내용을 기준으로 확인해야 한다.

예를 들어 중복 데이터가 발생했을 때 어떤 서비스는 400을 사용하고, 어떤 서비스는 409를 사용할 수 있다.

중요한 것은 Status Code 이름을 외우는 것보다, 현재 사용하는 API가 어떤 상황에서 어떤 코드를 반환하는지 확인하는 것이다.

문서와 실제 동작이 다를 수도 있다

API 문서에 적힌 내용과 실제 서버 동작이 다른 경우도 있다.

예를 들어 문서에는 name이 필수라고 적혀 있지만 실제 서버에서는 null을 허용할 수 있다.

반대로 문서에는 없는 필드가 실제 응답에 포함될 수도 있다.

문서에는 필수인데 실제로는 없어도 동작함
문서에는 선택인데 실제로는 필수임
문서와 실제 필드명이 다름
문서에 없는 Status Code가 반환됨
문서의 응답 예시와 실제 응답 구조가 다름

그래서 중요한 API는 문서만 읽고 끝내지 않고, Swagger UI나 Postman, curl 등을 이용해 직접 호출해보는 것이 좋다.

다만 문서와 실제 동작이 다르다고 해서 호출하는 쪽에서 임의로 맞춰서는 안 된다.

문서와 구현 중 어느 쪽이 팀에서 정한 계약에 맞는지 확인해야 한다.

확인된 내용은 문서나 테스트 코드에 반영해 같은 혼선이 반복되지 않도록 하는 것이 중요하다.

API 문서를 읽을 때 확인할 항목

API 문서를 볼 때는 다음 순서로 확인하면 된다.

1. 이 API는 어떤 기능을 하는가?
2. HTTP Method는 무엇인가?
3. Path는 무엇인가?
4. 인증이나 권한이 필요한가?
5. Path Parameter는 무엇인가?
6. Query Parameter는 무엇인가?
7. Request Body가 필요한가?
8. 필수 값과 선택 값은 무엇인가?
9. 각 값의 타입과 기본값은 무엇인가?
10. 성공하면 어떤 Status Code와 Body가 오는가?
11. 실패하면 어떤 Status Code와 Body가 오는가?
12. 조건에 따라 생략되거나 null이 되는 필드가 있는가?
13. 직접 호출했을 때 문서와 동일하게 동작하는가?

처음에는 항목이 많아 보일 수 있다.

하지만 몇 번 반복해서 확인하다 보면 자연스럽게 Method, Path, Parameter, Body, Response 순서로 보게 된다.

정리

API 문서는 서버와 클라이언트 사이의 약속이다.

단순히 호출 주소만 적힌 문서가 아니라 다음 내용을 함께 설명한다.

Method
Path
Authentication
Parameters
Request Body
Response Body
Status Code
Error Response

API 문서는 다음 한 문장으로 정리할 수 있다.

API 문서는 “어디로 호출하세요”가 아니라 “이런 형식으로 요청하면 이런 결과를 반환하겠습니다”라는 약속이다.

이 관점으로 보면 API 문서를 읽을 때도, 문서를 작성할 때도 기준이 생긴다.

좋은 API 문서는 호출하는 사람이 반복해서 질문하지 않아도 필요한 정보를 찾을 수 있게 만든다.

백엔드 개발자는 API를 구현하는 것뿐만 아니라, 다른 개발자가 쉽게 사용할 수 있도록 문서를 읽고 작성하는 감각도 함께 길러야 한다.