36. API 문서 읽는 법 배우기

API(Application Programming Interface)는 시스템 간 데이터를 주고받는 방식이에요. UX 기획자는 API가 어떻게 동작하는지 이해하고, 기획서에 API 연동 정보를 포함해야 개발자와 원활하게 협업할 수 있어요.

REST API & JSON: API 연동 시 필요한 데이터 포맷 이해하기

REST API란?
REST(Representational State Transfer) API는 웹에서 클라이언트(앱, 웹)와 서버가 데이터를 주고받는 방식이에요.
즉, 앱이 서버에서 데이터를 가져오거나 저장할 때 REST API를 이용합니다.

• REST API의 특징:
  • 클라이언트-서버 구조 : 프론트엔드(앱, 웹)와 백엔드(서버)가 분리되어 있음
  • HTTP 프로토콜 사용 : 브라우저에서 웹페이지를 요청하는 것과 비슷하게 API 요청도 HTTP 요청을 사용
  • 리소스를 URL로 표현 : API에서 데이터를 요청할 때 URL을 사용하여 요청함 

JSON이란? (API 데이터 포맷)
JSON(JavaScript Object Notation)은 API가 데이터를 주고받을 때 사용하는 데이터 형식이에요. 예를 들어, API 요청을 보내면 응답 데이터가 JSON 형태로 오게 됩니다.
 
 
JSON 구조 (JSON 데이터 예시 (사용자 정보 API 응답))

{
  "user_id": 123,
  "name": "김코나",
  "email": "uxplanner@example.com",
  "age": 30
}

• {}: JSON 객체
• "key": value 형식으로 데이터를 표현
• 문자열은 ""로 감싸고, 숫자는 그대로 사용

GET, POST, PUT, DELETE (서버와 데이터를 주고받는 HTTP 요청 방식)

REST API는 HTTP 요청 방식을 사용하여 데이터를 요청하고 처리합니다. 기획자가 요청 방식에 따른 API 동작을 이해하면 기획서에 API 연동 정보를 명확하게 정리할 수 있어요.
 
1. GET (데이터 조회)

• 데이터를 가져올 때 사용
• 서버에 저장된 정보를 변경하지 않음 (조회만 함)
• URL에 요청 정보를 포함함
• 예시: 사용자의 프로필 정보를 가져오는 API ↓

* 요청 (Client → Server)
GET /users/123

*응답 (Server → Client)
{
  "user_id": 123,
  "name": "김코나",
  "email": "uxplanner@example.com"
}

 
2. POST (데이터 생성)

• 새로운 데이터를 서버에 저장할 때 사용
• 요청 본문(body)에 데이터를 포함해야 함
• 예시 : 새로운 사용자 계정을 생성하는 API ↓

* 요청 (Client → Server)
POST /users

{
  "name": "김코나",
  "email": "uxplanner@example.com",
  "password": "securepassword"
}

* 응답 (Server → Client)
  "user_id": 124,
  "message": "User created successfully"
}

 

3. PUT (데이터 수정)

• 기존 데이터를 수정할 때 사용
• 전체 데이터를 수정 (일부 값만 변경할 경우 PATCH 사용)
• 예시 : 사용자 이메일을 변경하는 API

* 요청 (Client → Server)
PUT /users/123

{
  "name": "김코나",
  "email": "newemail@example.com"
}

* 응답 (Server → Client)
{
  "message": "User updated successfully"
}

 
4. DELETE (데이터 삭제)

• 데이터를 삭제할 때 사용
• 예시 : 사용자를 삭제하는 API ↓

* 요청 (Client → Server)
DELETE /users/123

*응답 (Server → Client)
{
  "message": "User deleted successfully"
}

 

API 문서 읽는 법 (기획서에 API 연동 정보 포함하기)

API 문서 예제 (사용자 관리 API)

요청 방식	엔드포인트	설명요청	예시응답	예시
GET	/users/123	사용자 정보 조회	GET /users/123	{ "user_id": 123, "name": "김코나" }
POST	/users	사용자 등록	POST /users + JSON 데이터	{ "message": "User created" }
PUT	/users/123	사용자 정보 수정	PUT /users/123 + JSON 데이터	{ "message": "User updated" }
DELETE	/users/123	사용자 삭제	DELETE /users/123	{ "message": "User deleted" }

 
기획서에 API 연동 정보 포함하는 방법은 UX 기획서에 API 호출이 필요한 기능이 있으면 API 정보도 정리하면 좋아요. 예를 들어, "회원가입" 기획서에 아래처럼 정리하면 개발팀이 쉽게 이해할 수 있어요.
 

[회원가입 기능]
요청 방식: **POST**
API 엔드포인트: **/users**
요청 데이터:
  {
    "name": "김코나",
    "email": "uxplanner@example.com",
    "password": "securepassword"
  }
응답 데이터:
  {
    "user_id": 124,
    "message": "User created successfully"
  }

 

API 문서를 읽고 활용하는 방법

• REST API는 클라이언트 - 서버 간 데이터 교환 방식
• JSON은 API에서 데이터를 주고받는 형식
• GET, POST, PUT, DELETE 요청 방식의 차이 이해하기
• 기획서에 API 연동 정보를 포함하면 개발 협업이 원활해짐