REST API 완벽 가이드: 웹의 공용어를 이해하자

1. REST API란?

REST API는 웹에서 데이터를 주고받는 약속(규칙)입니다. 마치 식당에서 주문하는 과정과 같습니다.

식당 비유: 손님(클라이언트)이 메뉴판을 보고 주문서(요청)를 작성해서 웨이터(HTTP)에게 전달하면, 주방(서버)에서 음식(데이터)을 만들어 보내줍니다.

REST의 의미

• REpresentational: 데이터의 "표현"
• State: 상태 (현재 데이터의 모습)
• Transfer: 전송 (클라이언트 ↔ 서버)

즉, "자원의 표현을 통해 상태를 전달하는 방식"입니다.

왜 REST API가 중요할까?

• 웹, 모바일, IoT 등 모든 클라이언트가 같은 방식으로 서버와 소통
• 언어/플랫폼에 독립적: Python, Java, JavaScript 어디서든 사용 가능
• HTTP 기반: 이미 전 세계에 구축된 웹 인프라를 그대로 활용

2. HTTP 메서드 상세

HTTP 메서드는 "이 데이터로 무엇을 할 것인가"를 서버에게 알려주는 동사입니다.

멱등성(Idempotency)이란?

같은 요청을 여러 번 보내도 결과가 같은 것을 말합니다.

• GET /products/1 → 몇 번을 보내도 같은 상품 정보 반환 (멱등)
• POST /products → 보낼 때마다 새 상품이 생성됨 (비멱등)
• DELETE /products/1 → 첫 번째는 삭제, 이후에는 404 (결과적으로 멱등)

GET 요청 예시

GET /api/products HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

POST 요청 예시

POST /api/products HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "무선 키보드",
  "price": 45000,
  "category": "전자기기"
}

3. HTTP 상태 코드

서버가 클라이언트에게 "요청 결과가 어땠는지" 알려주는 3자리 숫자입니다.

2xx: 성공

3xx: 리다이렉션

4xx: 클라이언트 오류

5xx: 서버 오류

4. URL / 엔드포인트 설계 원칙

REST API에서 URL은 "자원(Resource)의 위치"를 나타냅니다. 잘 설계된 URL은 그 자체로 API 문서 역할을 합니다.

좋은 URL 설계 규칙

1. 명사를 사용: /products (O) vs /getProducts (X)
2. 복수형 사용: /users (O) vs /user (X)
3. 계층 구조 활용: /users/123/orders (사용자 123의 주문 목록)
4. 소문자 + 하이픈: /order-items (O) vs /OrderItems (X)
5. 동사 사용 자제: 동작은 HTTP 메서드로 표현

URL 설계 예시

GET    /api/products          → 모든 상품 조회
GET    /api/products/42       → 42번 상품 조회
POST   /api/products          → 새 상품 생성
PUT    /api/products/42       → 42번 상품 수정
DELETE /api/products/42       → 42번 상품 삭제
GET    /api/products?category=전자기기&sort=price
                               → 필터 + 정렬

5. 헤더와 인증

HTTP 헤더는 요청/응답의 메타 정보를 담고 있습니다. 편지의 봉투 정보와 비슷합니다.

주요 요청 헤더

인증 방식 비교

6. JSON 데이터 형식

JSON (JavaScript Object Notation)은 REST API에서 데이터를 주고받는 가장 대표적인 형식입니다.

JSON 기본 문법

{
  "name": "김철수",        // 문자열: 큰따옴표
  "age": 28,              // 숫자: 따옴표 없이
  "isPremium": true,      // 불리언: true / false
  "address": null,        // null: 값 없음
  "hobbies": ["독서", "코딩"],  // 배열
  "company": {            // 중첩 객체
    "name": "테크스타트",
    "position": "개발자"
  }
}

API 응답 예시 (페이지네이션 포함)

{
  "status": "success",
  "data": [
    { "id": 1, "name": "노트북", "price": 1200000 },
    { "id": 2, "name": "키보드", "price": 89000 }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42
  }
}

7. RESTful 설계 6대 원칙

Roy Fielding이 2000년 박사 논문에서 정의한 REST 아키텍처의 제약 조건입니다.

1. 클라이언트-서버 분리 (Client-Server)

   클라이언트와 서버는 독립적으로 발전할 수 있어야 합니다. UI(클라이언트)와 데이터 저장(서버)을 분리합니다.

2. 무상태 (Stateless)

   서버는 클라이언트의 상태를 저장하지 않습니다. 매 요청에 필요한 모든 정보를 포함해야 합니다.

   비유: 식당에서 매번 "저는 김철수이고, 알러지가 있고, VIP입니다"라고 말해야 합니다.

3. 캐시 가능 (Cacheable)

   응답 데이터는 캐시할 수 있어야 합니다. 같은 데이터를 반복 요청하지 않도록 합니다.

4. 계층화 시스템 (Layered System)

   클라이언트는 서버에 직접 연결되는지, 중간 서버(로드밸런서, 캐시)를 거치는지 알 필요 없습니다.

5. 통일된 인터페이스 (Uniform Interface)

   일관된 URL 구조, HTTP 메서드, 응답 형식을 사용합니다. REST의 핵심 원칙입니다.

6. 주문형 코드 (Code on Demand, 선택)

   서버가 클라이언트에 실행 가능한 코드(JavaScript 등)를 전송할 수 있습니다.

8. 실무 활용

8.1 REST API 설계 팁

• 버전 관리: /api/v1/products, /api/v2/products
• 에러 응답 통일: { "error": { "code": 404, "message": "상품을 찾을 수 없습니다" } }
• 페이지네이션: ?page=1&limit=20 또는 커서 기반
• 필터/정렬: ?category=전자기기&sort=-price (마이너스 = 내림차순)
• HATEOAS: 응답에 관련 링크 포함 (자기 설명적 API)

8.2 대표적인 REST API 서비스

• GitHub API: GET /repos/{owner}/{repo}/issues
• 카카오 API: GET /v2/search/web?query=검색어
• 네이버 API: GET /v1/search/news.json?query=IT
• Stripe API: POST /v1/charges (결제 생성)

8.3 REST vs GraphQL 비교

Q&A: 자주 묻는 질문

Q1. REST API와 RESTful API의 차이는?
A. REST는 아키텍처 스타일이고, RESTful은 REST 원칙을 잘 지킨 API를 말합니다. 엄격히 6대 원칙을 모두 지킨 API만 RESTful이라 부를 수 있습니다.

Q2. PUT과 PATCH의 차이가 뭔가요?
A. PUT은 리소스를 전체 교체하고, PATCH는 일부만 수정합니다. 예를 들어 이름만 바꾸고 싶을 때 PUT은 모든 필드를 보내야 하지만, PATCH는 이름 필드만 보내면 됩니다.

Q3. API Key와 Bearer Token의 차이는?
A. API Key는 애플리케이션을 식별하는 고정 키이고, Bearer Token(주로 JWT)은 사용자를 인증하는 임시 토큰입니다. Token은 만료 시간이 있어 더 안전합니다.

Q4. 왜 DELETE 응답에 본문이 없나요? (204)
A. 삭제된 리소스는 더 이상 존재하지 않으므로 보낼 데이터가 없습니다. 204 No Content는 "성공했지만 전달할 내용은 없어요"라는 뜻입니다.

Q5. REST API에서 상태(State)를 어디에 저장하나요?
A. REST는 무상태(Stateless)입니다. 서버는 상태를 저장하지 않고, 클라이언트가 매 요청마다 인증 토큰 등 필요한 정보를 함께 보냅니다.

정리