API 설계 원칙 — RESTful 성숙도 모델과 좋은 API의 조건

모든 요청이 하나의 URL, 하나의 HTTP 메서드(POST)

POST /api
{
  "action": "getUser",
  "userId": 1
}

POST /api
{
  "action": "createOrder",
  "productId": 5,
  "quantity": 2
}

리소스별로 URL을 분리

POST /users/1       → 사용자 조회
POST /orders        → 주문 생성
POST /products/5    → 상품 조회

HTTP 메서드를 올바르게 사용

GET    /users/1         → 사용자 조회
POST   /users           → 사용자 생성
PUT    /users/1         → 사용자 전체 수정
PATCH  /users/1         → 사용자 부분 수정
DELETE /users/1         → 사용자 삭제

// 응답에 다음 가능한 액션의 링크를 포함
{
  "id": 1,
  "name": "Alice",
  "links": [
    { "rel": "self", "href": "/users/1" },
    { "rel": "orders", "href": "/users/1/orders" },
    { "rel": "update", "href": "/users/1", "method": "PUT" }
  ]
}

✓ 좋은 예:
GET  /users                    → 사용자 목록
GET  /users/1                  → 특정 사용자
GET  /users/1/orders           → 사용자의 주문 목록
GET  /users/1/orders/5         → 사용자의 특정 주문
POST /users/1/orders           → 사용자의 주문 생성

✗ 나쁜 예:
GET  /getUser?id=1             → 동사 사용
GET  /user/1                   → 단수형
POST /users/1/createOrder      → URL에 동사
GET  /Users/1                  → 대문자

2xx 성공:
  200 OK           → 일반적인 성공
  201 Created      → 리소스 생성 성공 (POST)
  204 No Content   → 성공, 응답 본문 없음 (DELETE)

4xx 클라이언트 에러:
  400 Bad Request  → 잘못된 요청 (유효성 검증 실패)
  401 Unauthorized → 인증 필요
  403 Forbidden    → 인증됐지만 권한 없음
  404 Not Found    → 리소스 없음
  409 Conflict     → 충돌 (중복 등록 등)
  422 Unprocessable → 문법은 맞지만 처리 불가

5xx 서버 에러:
  500 Internal Server Error → 서버 내부 오류
  503 Service Unavailable   → 서비스 일시 중단

// 일관된 에러 응답 구조
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "입력값이 유효하지 않습니다",
    "details": [
      {
        "field": "email",
        "message": "올바른 이메일 형식이 아닙니다"
      },
      {
        "field": "name",
        "message": "이름은 2자 이상이어야 합니다"
      }
    ]
  }
}

커서 기반 (추천):
GET /posts?cursor=eyJpZCI6MTAwfQ&limit=20

오프셋 기반 (간단하지만 대용량에서 느림):
GET /posts?page=3&size=20

응답:
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIwfQ",
    "has_next": true,
    "total_count": 1500
  }
}

필터링:
GET /products?category=electronics&min_price=10000

정렬:
GET /products?sort=-price,name    (price 내림차순, name 오름차순)

필드 선택:
GET /users/1?fields=id,name,email  (필요한 필드만 반환)

REST:
GET /users/1           → 사용자 전체 정보 반환 (Over-fetching)
GET /users/1/orders    → 별도 요청 필요 (Under-fetching)

GraphQL:
POST /graphql
{
  query {
    user(id: 1) {
      name
      email
      orders(first: 5) {
        total
        status
      }
    }
  }
}
→ 한 번의 요청으로 필요한 것만 정확히 반환