HTTP / REST API 설계

메서드는 ‘리소스에 무엇을 할 것인가’를 나타낸다. 동작을 URL에 담지 않고 (예: /users/delete) 메서드로 표현하는 것이 REST의 출발점이다.

API를 견고하게 만들려면 각 메서드의 ‘안전성(safe)’과 ‘멱등성(idempotent)’을 이해해야 한다. 특히 네트워크 재시도 상황에서 중요하다.

상태 코드는 응답의 결과를 한눈에 알려주는 신호다. 200으로 뭉뚱그리고 본문에{ success: false }를 넣는 방식은 HTTP의 의미를 버리는 안티패턴이다.

URI는 ‘행위’가 아니라 ‘자원(명사)’을 가리켜야 한다. 행위는 메서드가, 대상은 URI가 표현한다.

# ❌ 동사·행위가 URI에 노출
POST /createUser
GET  /getUserOrders?userId=42
POST /users/42/delete

# ✅ 명사(자원) 중심, 계층 구조
POST   /users                  # 사용자 생성
GET    /users/42               # 단일 조회
GET    /users/42/orders        # 하위 컬렉션
DELETE /users/42               # 삭제

• 컬렉션은 복수형: /users, /orders처럼 복수 명사로 통일한다.
• 계층으로 소유 관계 표현: /users/42/orders는 42번 사용자의 주문을 의미한다.
• 필터·정렬·페이징은 쿼리스트링: /orders?status=paid&sort=-createdAt&page=2처럼 자원의 부분 집합을 쿼리로 표현한다.

에러 응답 형식이 API마다 제각각이면 클라이언트가 매번 다르게 파싱해야 한다. RFC 7807(Problem Details)은 에러 본문의 표준 형태를 정의해 이 문제를 해결한다.

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/duplicate-email",
  "title": "이미 사용 중인 이메일입니다",
  "status": 409,
  "detail": "user@example.com 은 이미 가입된 이메일입니다.",
  "instance": "/users"
}