[2025 하계 모각코] 3회차 API 명세서에 대하여..

2025 멋쟁이사자처럼 대학 13기 중앙해커톤을 준비하기 위해 API 명세서에 대해 공부하였다.

 

 

API는 식당의 '메뉴판'이자 '점원'이에요

가장 쉽게 생각해 봅시다.

• 앱 화면 (프론트엔드) = 손님
• 데이터가 저장된 컴퓨터 (백엔드 서버) = 주방
• API = 손님(앱)과 주방(서버)을 연결하는 점원

손님은 점원에게 주문을 하고, 점원은 주문을 주방에 전달하죠. 그리고 주방에서 나온 음식을 다시 손님에게 가져다줍니다. API가 딱 이 역할이에요. API 명세서는 이 점원이 사용하는 아주 상세한 메뉴판이자 업무 지침서라고 생각하면 완벽해요.

---

Notion 명세서, 하나씩 채워볼까요?

이제 그 '업무 지침서'의 각 항목이 무슨 뜻인지 알아봅시다.

1. 기능 (Function)

• 무슨 뜻인가요?: "그래서 뭘 하고 싶은 건데?" 에 대한 대답이에요.
• 식당 비유: "스테이크 주문하기", "자리 있는지 물어보기", "계산하기" 같은 손님의 목적을 한글로 알기 쉽게 적는 칸이에요.
• 예시: "내 프로필 정보 불러오기", "회원가입하기", "로그인하기"

2. HTTP 메서드 (Method)

• 무슨 뜻인가요?: "어떤 방식으로 할 건데?" 라는 행동 방식이에요. 점원의 구체적인 행동이죠. 딱 4가지만 기억하면 돼요.

메서드	식당 비유	핵심 행동
GET	"메뉴판 좀 '주세요'."	데이터 조회 (가져오기)
POST	"이걸로 주문할게요."	데이터 생성 (새로 만들기)
PUT	"주문 싹 다 바꾸고 이걸로 '바꿔주세요'."	데이터 전체 수정 (통째로 바꾸기)
DELETE	"이 주문 '취소할게요'."	데이터 삭제 (없애기)

• 예시: "내 프로필 정보 불러오기"는 있는 정보를 가져오는 거니까 GET을 쓰면 되겠죠? "회원가입하기"는 새로운 회원 정보를 만드는 거니까 POST를 씁니다.

3. API Path (경로)

• 무슨 뜻인가요?: "어디에 있는 데이터에 대한 건데?" 라는 상세 주소예요.
• 식당 비유: "A코스 스테이크", "5번 테이블의 예약 정보" 처럼, 점원이 주방의 어떤 요리사나 장부 담당자에게 가야 할지 알려주는 목적지 주소와 같아요. 보통 / 로 시작해요.
• 예시:
  • 사용자(users)에 관련된 기능이라면: /users
  • 12번 회원의 정보라면: /users/123
  • 게시글(posts)에 관련된 기능이라면: /posts

4. Request (요청)

• 무슨 뜻인가요?: "목적을 이루기 위해 필요한 정보" 입니다.
• 식당 비유: 손님이 스테이크를 주문(POST)할 때 그냥 "스테이크 주세요"라고 안 하죠? "굽기는 미디엄 레어, 사이드 메뉴는 감자튀김으로 주세요" 라고 상세하게 적는 주문서예요. 이 주문서 양식이 바로 Request입니다.
• 왜 페이지로 연결되어 있나요?: 바로 그 **'주문서 양식'**을 미리 정해두는 거예요. Notion 이미지에서 UserProfileRequest 페이지는 "프로필 정보를 요청할 때는 이런이런 항목들을 채워서 보내야 해!" 라는 약속을 적어둔 문서인 셈이죠.
  • 예를 들어, UserProfileRequest 페이지 안에는 {"nickname": "바꿀 닉네임", "age": 20} 과 같이 어떤 정보를 보내야 하는지 그 구조(JSON)가 적혀있어요.

5. Response (응답)

• 무슨 뜻인가요?: "요청에 대한 서버의 대답" 입니다.
• 식당 비유: 손님의 주문(Request)을 받은 점원이 주방에서 가져온 결과물이에요.
  • 성공: 손님이 주문한 스테이크 접시 (Response)가 나왔어요. 접시 위에는 스테이크, 감자튀김, 소스가 있죠.
  • 실패: 점원이 와서 "죄송합니다, 스테이크 재료가 다 떨어졌네요." 라고 말하는 것. 이것도 중요한 Response(응답)입니다.
• 왜 페이지로 연결되어 있나요?: 이것도 마찬가지로 '결과물이 어떻게 생겼는지' 그 양식을 미리 약속해두는 거예요. UserProfileResponse 페이지는 "프로필 정보를 성공적으로 주면, 이런이런 항목들이 담겨서 갈 거야!" 라고 알려주는 설명서입니다.
  • 예를 들어, UserProfileResponse 페이지 안에는 {"userId": 123, "nickname": "방금바꾼닉네임", "email": "user@example.com"} 과 같이 어떤 정보가 담겨서 오는지 그 구조(JSON)가 적혀있어요.

---

실전! 표 채우기 예시

자, 그럼 "내 프로필 닉네임을 바꾸는" 기능을 명세서에 직접 작성해볼까요?

기능	HTTP 메서드	API Path	Request	Response
내 닉네임 수정하기	PUT	/users/me/profile	(📄UpdateProfileRequest 페이지 링크)	(📄UserProfileResponse 페이지 링크)

이제 각 링크된 페이지 안에는 뭐가 들어갈까요?

📄UpdateProfileRequest 페이지 내용 (주문서 양식: "이렇게 보내주세요!")

JSON

 

{
  "nickname": "새로운멋진닉네임"
}

📄UserProfileResponse 페이지 내용 (결과물 설명서: "성공하면 이렇게 드립니다!")

JSON

 

{
  "userId": 1,
  "email": "my-email@gmail.com",
  "nickname": "새로운멋진닉네임"
}

어때요? 이제 저 표가 하나의 완성된 '업무 지침'으로 보이지 않나요? "내 닉네임을 바꾸고 싶으면(기능), 데이터를 수정(PUT)할 거고, /users/me/profile 주소(API Path)로, UpdateProfileRequest 양식에 맞춰(Request) 요청해. 그럼 UserProfileResponse 양식에 맞춰서(Response) 대답해줄게!" 라는 뜻이 되는 거죠.