RESTful API 설계 원칙 (Richardson Maturity)

Level 0: HTTP를 RPC로 사용
- 모든 요청이 POST /api
- body로 action 지정

Level 1: 리소스 분리
- /users, /posts (URL이 리소스)
- 메서드는 여전히 POST

Level 2: HTTP 메서드 활용
- GET, POST, PUT, DELETE
- 상태 코드 (200, 201, 404)
- ← 대부분의 "REST API"

Level 3: HATEOAS (하이퍼미디어)
- 응답에 다음 액션 링크 포함
- 진짜 RESTful

✅ 리소스 (명사)
GET    /users                # 목록
GET    /users/123            # 상세
POST   /users                # 생성
PATCH  /users/123            # 수정
DELETE /users/123            # 삭제

✅ 중첩 리소스 (1단계만)
GET /users/123/posts
POST /users/123/posts

❌ 동사 사용 금지
GET /getUsers
POST /createUser
POST /users/123/delete


✅ 검색·필터는 쿼리 파라미터
GET /posts?author=alice&status=published&page=2&limit=20

✅ 정렬
GET /posts?sort=createdAt:desc
GET /posts?sort=-createdAt,+title  (- desc, + asc)

| 메서드 | 멱등성 | 안전 | 용도 |
|---|---|---|---|
| GET | ✅ | ✅ | 조회 |
| HEAD | ✅ | ✅ | 메타데이터만 |
| OPTIONS | ✅ | ✅ | CORS preflight |
| POST | ❌ | ❌ | 생성·복잡 작업 |
| PUT | ✅ | ❌ | 전체 교체 |
| PATCH | ❌* | ❌ | 부분 수정 |
| DELETE | ✅ | ❌ | 삭제 |


멱등성: 여러 번 호출해도 결과 동일
* PATCH는 보통 멱등이지만 케이스에 따라 다름

2xx 성공:
- 200 OK: 일반 성공
- 201 Created: 리소스 생성 (POST 응답)
- 202 Accepted: 비동기 처리 시작
- 204 No Content: 성공 + 본문 없음 (DELETE)

4xx 클라이언트 오류:
- 400 Bad Request: 잘못된 요청 (검증 실패)
- 401 Unauthorized: 인증 필요
- 403 Forbidden: 권한 없음
- 404 Not Found: 리소스 없음
- 409 Conflict: 중복 (이메일 존재)
- 422 Unprocessable Entity: 검증 실패 (semantic)
- 429 Too Many Requests: rate limit

5xx 서버 오류:
- 500 Internal Server Error: 서버 오류
- 502 Bad Gateway: 업스트림 오류
- 503 Service Unavailable: 일시 중단
- 504 Gateway Timeout: 업스트림 타임아웃

// 단일 리소스
GET /users/123
200 OK
{
  "id": "123",
  "name": "Alice",
  "email": "alice@example.com",
  "createdAt": "2026-04-29T10:00:00Z"
}


// 목록 + 메타
GET /users?page=2&limit=20
200 OK
{
  "data": [
    { "id": "121", "name": "..." },
    ...
  ],
  "meta": {
    "page": 2, "limit": 20,
    "total": 1234, "totalPages": 62
  },
  "links": {
    "self": "/users?page=2&limit=20",
    "next": "/users?page=3&limit=20",
    "prev": "/users?page=1&limit=20"
  }
}


// 에러 (RFC 7807)
400 Bad Request
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Email is required",
  "instance": "/users",
  "errors": [
    { "field": "email", "message": "required" }
  ]
}

GET /orders/123
{
  "id": "123",
  "status": "pending",
  "total": 50000,
  "_links": {
    "self":   { "href": "/orders/123" },
    "cancel": { "href": "/orders/123/cancel", "method": "POST" },
    "pay":    { "href": "/orders/123/pay", "method": "POST" },
    "user":   { "href": "/users/456" }
  }
}


// 클라이언트는 _links 따라가며 동작
// → URL 변경 시 클라이언트 수정 불필요