REST API 설계 체크리스트 2026 — 엔드포인트 네이밍부터 에러 응답까지 실무 35항목

엔드포인트 네이밍 — 좋은 예와 나쁜 예 비교
# ✅ 좋은 패턴
GET    /api/v1/users          # 목록 조회
GET    /api/v1/users/123      # 단건 조회
POST   /api/v1/users          # 생성
PATCH  /api/v1/users/123      # 부분 수정
DELETE /api/v1/users/123      # 삭제
POST   /api/v1/users/123/deactivate  # 커스텀 액션

# ❌ 나쁜 패턴
GET    /api/v1/getUsers
POST   /api/v1/user/create
POST   /api/v1/deactivateUser?id=123
GET    /api/v1/User/123        # 대문자

에러 응답 — RFC 9457 Problem Details 기반 구조 예시
// 유효성 에러 (422)
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "요청 본문에 유효하지 않은 필드가 있습니다.",
  "errors": [
    { "field": "email", "message": "이메일 형식이 올바르지 않습니다" },
    { "field": "age", "message": "0 이상의 정수여야 합니다" }
  ]
}

// 리소스 없음 (404)
{
  "type": "https://api.example.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "ID 456에 해당하는 주문을 찾을 수 없습니다."
}

커서 기반 페이지네이션 응답 구조 예시
// GET /api/v1/notifications?cursor=eyJpZCI6MTAwfQ&limit=20
{
  "data": [
    { "id": 101, "message": "새 댓글", "createdAt": "2026-03-27T09:00:00Z" },
    { "id": 102, "message": "좋아요", "createdAt": "2026-03-27T09:01:00Z" }
  ],
  "meta": {
    "nextCursor": "eyJpZCI6MTIwfQ",
    "hasNext": true,
    "limit": 20
  }
}

Idempotency Key — 결제 API 요청 예시
# 첫 번째 요청
curl -X POST https://api.example.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order-abc-123-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50000, "currency": "KRW", "method": "card"}'

# 네트워크 타임아웃으로 같은 요청 재시도 — 중복 결제 안 됨
curl -X POST https://api.example.com/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order-abc-123-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 50000, "currency": "KRW", "method": "card"}'
# → 서버는 첫 번째 요청의 응답을 그대로 반환 (201, 같은 payment_id)

Spectral — OpenAPI 린터 룰셋 예시 (.spectral.yml)
extends: spectral:oas
rules:
  paths-kebab-case:
    description: URL 경로는 kebab-case
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9-]+|/{[a-zA-Z]+})+$"
  operation-error-response:
    description: 모든 엔드포인트에 400, 500 에러 응답 정의 필수
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      - field: "400"
        function: truthy
      - field: "500"
        function: truthy
  pagination-meta:
    description: 목록 API 응답에 meta 필드 필수
    given: $.paths[*].get.responses.200.content.application/json.schema
    then:
      field: properties.meta
      function: truthy

Spectral CLI 실행 명령어
npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml --ruleset .spectral.yml