개발 효율을 높이는 API 명세서 작성의 5단계 원칙

왜 ‘기능 위주’의 명세서가 위험할까?

이전 프로젝트에서 API 명세서를 작성할 때, “이런 기능이 필요하니까 이렇게 만들자” 는 생각으로 기능 구현에만 급급했던 적이 있습니다.

그런데 막상 개발이 시작되자 문제가 드러났습니다. 로직을 구현하다 보니 데이터 구조가 맞지 않아 명세서를 수정해야 하는 일이 잦았습니다. 개발이 시작된 뒤 명세서를 고치는 건 문서 한 줄을 바꾸는 일이 아닙니다. 이미 짜인 코드의 흐름을 꼬이게 만드는 위험한 작업이었습니다.

지난 경험과 이번 강의를 계기로, 개발을 시작하기 전의 문서화(설계) 가 왜 중요한지, 또 어떻게 하면 단계적으로 탄탄한 명세서를 쓸 수 있는지 정리했습니다.

API 명세서 작성을 위한 5단계 질문

기능만 떠올려 나열하는 대신, 다음 다섯 가지 질문을 순서대로 던져 보면 명세서가 한결 명확해집니다.

1. Who (누가 API를 사용하는가?)

• 이 API를 호출하는 대상이 누구인지부터 분명히 합니다.
• 내부 서비스용인지, 외부 파트너사용인지, 관리자 전용인지에 따라 필요한 보안 인증 방식과 데이터의 상세 수준이 달라지기 때문입니다.

2. What (무엇을 다룰 것인가?)

• API가 제어할 리소스(Resource)를 정의합니다.
• “로그인 기능”이 아니라 “사용자(User) 정보”나 “세션(Session)” 같은 리소스로 접근해야 설계가 RESTful해집니다.

3. How (어떻게 하는가?)

• HTTP Method와 Endpoint(URI) 구조를 설계합니다.
• 메서드는 다음 원칙을 따릅니다.
  • GET: 리소스 조회
  • POST: 리소스 생성
  • PUT/PATCH: 리소스 수정
  • DELETE: 리소스 삭제

4. Parameters (무엇이 필요한가?)

• 요청에 필요한 모든 데이터를 정의합니다. (Header, Body, Query String 등)
• 각 파라미터의 데이터 타입, 필수 여부, 제약 조건까지 함께 명시합니다.

5. Returns (무엇을 반환하는가?)

• 작업 결과로 반환할 응답 데이터와 HTTP 상태 코드를 정의합니다.
• 성공(200, 201)만이 아니라 예상되는 실패 상황(400, 401, 404 등)의 에러 응답 구조도 빠짐없이 담습니다.

실전 응용 예시: 게시글 생성 API

배운 내용을 바탕으로 간단한 게시글 작성 API 명세를 직접 짜 봤습니다.

• Who : 로그인한 커뮤니티 사용자
• What : 게시글(Post)
• How : POST /api/v1/posts
• Parameters :
  • Authorization : Bearer {token} (Header, 필수)
  • title : 제목 (Body, String, 필수, 최대 50자)
  • content : 본문 (Body, String, 필수)
• Returns :
  • Success (201 Created) : 생성된 게시글의 ID 및 생성 시간 반환
  • Fail (400 Bad Request) : 제목 누락 등 유효성 검사 실패 메시지

// Response Body Example (Success)
{
  "status": "success",
  "data": {
    "postId": 1024,
    "createdAt": "2026-03-09T17:00:00Z"
  }
}

회고 및 느낀 점

앞으로 지키고 싶은 두 가지가 있습니다. 우선 ‘내가 만들기 편한 API’가 아니라 ‘사용자(프론트엔드 개발자 등)가 쓰기 편한 API’인지를 먼저 따져 보겠습니다. 그리고 성공 응답만큼 실패 응답도 꼼꼼히 정의해 트러블슈팅 시간을 줄여 주는 명세서를 쓰겠습니다.

명세서는 한 번 쓰고 끝나는 문서가 아니라 팀원과 소통하는 도구입니다. 이 다섯 단계를 습관으로 삼으면 ‘꼬이지 않는 개발’에 한 걸음 더 가까워집니다.