REST API 설계 베스트 프랙티스 2025: 개발자가 반드시 알아야 할 API 설계 원칙과 실전 패턴

# 1단계: OpenAPI 명세 먼저 작성
openapi: 3.1.0
info:
  title: User Service API
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success

설계 순서:
1. API 명세 작성 (OpenAPI)
2. 명세 리뷰 및 합의
3. Mock 서버로 프론트엔드 개발 시작
4. 백엔드 구현
5. Contract Testing

POST /api HTTP/1.1
Content-Type: application/json

{
  "action": "getUser",
  "userId": 123
}

POST /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "action": "get"
}

GET /api/users/123 HTTP/1.1
Accept: application/json

---

PUT /api/users/123 HTTP/1.1
Content-Type: application/json

{
  "name": "Updated Name",
  "email": "user@example.com"
}

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "_links": {
    "self": { "href": "/api/v1/users/123" },
    "orders": { "href": "/api/v1/users/123/orders" },
    "update": { "href": "/api/v1/users/123", "method": "PUT" },
    "delete": { "href": "/api/v1/users/123", "method": "DELETE" }
  }
}

# 컬렉션
GET    /api/v1/users                    # 사용자 목록
POST   /api/v1/users                    # 사용자 생성

# 개별 리소스
GET    /api/v1/users/123                # 특정 사용자 조회
PUT    /api/v1/users/123                # 사용자 전체 수정
PATCH  /api/v1/users/123                # 사용자 부분 수정
DELETE /api/v1/users/123                # 사용자 삭제

# 중첩 리소스
GET    /api/v1/users/123/orders         # 사용자의 주문 목록
GET    /api/v1/users/123/orders/456     # 특정 주문 조회
POST   /api/v1/users/123/orders         # 주문 생성

# 필터링
GET    /api/v1/users?role=admin         # 관리자만 조회
GET    /api/v1/products?category=electronics&min_price=100

# 검색
GET    /api/v1/users/search?q=john      # 사용자 검색

# 상태 변경 (action)
POST   /api/v1/users/123/activate       # 계정 활성화
POST   /api/v1/orders/456/cancel        # 주문 취소
POST   /api/v1/payments/789/refund      # 결제 환불

# 배치 작업
POST   /api/v1/users/batch              # 일괄 생성
DELETE /api/v1/users/batch              # 일괄 삭제

# 서브 리소스 (singleton)
GET    /api/v1/users/123/profile        # 사용자 프로필
PUT    /api/v1/users/123/avatar         # 아바타 업데이트

GET     리소스 조회 (읽기)        — 안전, 멱등
POST    리소스 생성 (쓰기)        — 안전하지 않음, 비멱등
PUT     리소스 전체 교체 (덮어쓰기) — 안전하지 않음, 멱등
PATCH   리소스 부분 수정           — 안전하지 않음, 비멱등(일반적)
DELETE  리소스 삭제               — 안전하지 않음, 멱등
OPTIONS 지원 메서드 확인           — 안전, 멱등
HEAD    GET과 동일, 본문 없음      — 안전, 멱등

// PUT: 전체 리소스 교체 (모든 필드 필요)
PUT /api/v1/users/123
{
  "name": "John Doe",
  "email": "john@example.com",
  "age": 30,
  "role": "admin"
}

// PATCH: 부분 수정 (변경 필드만)
PATCH /api/v1/users/123
{
  "age": 31
}

POST /api/v1/users          → 서버가 ID 생성 (201 Created + Location 헤더)
PUT  /api/v1/users/123      → 클라이언트가 ID 지정 (존재하면 교체, 없으면 생성)

요청 성공?
├── YES → 데이터 반환? → 200 OK
│         리소스 생성? → 201 Created
│         비동기 작업? → 202 Accepted
│         본문 없음?   → 204 No Content
└── NO  → 인증 문제?   → 401 / 403
          요청 문제?   → 400 / 422
          리소스 없음? → 404
          충돌?       → 409
          서버 문제?   → 500 / 502 / 503

GET /api/v1/users?page=3&size=20

{
  "data": [
    { "id": 41, "name": "User 41" },
    { "id": 42, "name": "User 42" }
  ],
  "pagination": {
    "page": 3,
    "size": 20,
    "total_items": 1000,
    "total_pages": 50,
    "has_next": true,
    "has_prev": true
  }
}

-- SQL 구현
SELECT * FROM users
ORDER BY id
LIMIT 20 OFFSET 40;
-- 문제: OFFSET 10000이면 10000개를 건너뛰어야 함 → 성능 저하

GET /api/v1/users?cursor=eyJpZCI6NDJ9&limit=20

{
  "data": [
    { "id": 43, "name": "User 43" },
    { "id": 44, "name": "User 44" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6NjJ9",
    "has_next": true,
    "limit": 20
  }
}

// Node.js 구현
async function getCursorPaginatedUsers(cursor, limit = 20) {
  let query = 'SELECT * FROM users'
  const params = []

  if (cursor) {
    const decoded = JSON.parse(Buffer.from(cursor, 'base64').toString())
    query += ' WHERE id > $1'
    params.push(decoded.id)
  }

  query += ' ORDER BY id ASC LIMIT $' + (params.length + 1)
  params.push(limit + 1) // +1로 다음 페이지 존재 여부 확인

  const rows = await db.query(query, params)
  const hasNext = rows.length > limit
  const data = hasNext ? rows.slice(0, limit) : rows

  const nextCursor = hasNext
    ? Buffer.from(JSON.stringify({ id: data[data.length - 1].id })).toString('base64')
    : null

  return { data, pagination: { next_cursor: nextCursor, has_next: hasNext, limit } }
}

GET /api/v1/users?after_date=2025-01-15&after_id=42&limit=20&sort=created_at

-- SQL 구현: created_at + id 복합 키
SELECT * FROM users
WHERE (created_at, id) > ('2025-01-15', 42)
ORDER BY created_at ASC, id ASC
LIMIT 20;

# 단순 필터
GET /api/v1/products?category=electronics&brand=apple

# 비교 연산자
GET /api/v1/products?price_gte=100&price_lte=500

# 배열 필터
GET /api/v1/products?tags=wireless,bluetooth

# 날짜 범위
GET /api/v1/orders?created_after=2025-01-01&created_before=2025-03-31

# 단일 정렬
GET /api/v1/products?sort=price

# 내림차순
GET /api/v1/products?sort=-price

# 복합 정렬
GET /api/v1/products?sort=-created_at,name

# 필요한 필드만 요청 (응답 크기 감소)
GET /api/v1/users?fields=id,name,email

# 관련 리소스 포함
GET /api/v1/users/123?include=orders,profile

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

# RQL (Resource Query Language) 스타일
GET /api/v1/products?filter=category==electronics;price=gt=100;brand=in=(apple,samsung)

GET /api/v1/users/123
GET /api/v2/users/123

GET /api/users/123
Accept: application/vnd.myapp.v2+json

GET /api/users/123?version=2

1. Major 버전만 관리 (v1, v2) — Minor/Patch는 하위 호환
2. 최소 2개 버전 동시 지원
3. Deprecation 정책 공개 (최소 6개월 유예)
4. Sunset 헤더 사용

  Sunset: Sat, 01 Mar 2026 00:00:00 GMT
  Deprecation: true
  Link: <https://api.example.com/v2/users>; rel="successor-version"

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "요청 본문에 유효하지 않은 필드가 있습니다.",
  "instance": "/api/v1/users",
  "timestamp": "2025-03-15T10:30:00Z",
  "errors": [
    {
      "field": "email",
      "code": "INVALID_FORMAT",
      "message": "유효한 이메일 주소를 입력하세요."
    },
    {
      "field": "age",
      "code": "OUT_OF_RANGE",
      "message": "나이는 0에서 150 사이여야 합니다."
    }
  ]
}

// 에러 클래스 정의
class ApiError extends Error {
  constructor(status, type, title, detail, errors = []) {
    super(detail)
    this.status = status
    this.type = type
    this.title = title
    this.detail = detail
    this.errors = errors
  }
}

// 팩토리 함수
const ApiErrors = {
  notFound: (resource, id) =>
    new ApiError(
      404,
      'https://api.example.com/errors/not-found',
      'Resource Not Found',
      `${resource} with id ${id} was not found.`
    ),

  validationFailed: (errors) =>
    new ApiError(
      422,
      'https://api.example.com/errors/validation',
      'Validation Failed',
      'The request body contains invalid fields.',
      errors
    ),

  rateLimited: (retryAfter) =>
    new ApiError(
      429,
      'https://api.example.com/errors/rate-limit',
      'Rate Limit Exceeded',
      `Too many requests. Retry after ${retryAfter} seconds.`
    ),
}

// Express 에러 핸들러
app.use((err, req, res, next) => {
  if (err instanceof ApiError) {
    return res.status(err.status).json({
      type: err.type,
      title: err.title,
      status: err.status,
      detail: err.detail,
      instance: req.originalUrl,
      timestamp: new Date().toISOString(),
      errors: err.errors.length > 0 ? err.errors : undefined,
    })
  }

  // 예상치 못한 에러
  console.error('Unexpected error:', err)
  res.status(500).json({
    type: 'https://api.example.com/errors/internal',
    title: 'Internal Server Error',
    status: 500,
    detail: 'An unexpected error occurred.',
    instance: req.originalUrl,
    timestamp: new Date().toISOString(),
  })
})

// i18n 에러 메시지
const errorMessages = {
  INVALID_EMAIL: {
    ko: '유효한 이메일 주소를 입력하세요.',
    en: 'Please enter a valid email address.',
    ja: '有効なメールアドレスを入力してください。',
  },
  FIELD_REQUIRED: {
    ko: '필수 입력 항목입니다.',
    en: 'This field is required.',
    ja: '必須入力項目です。',
  },
}

function getErrorMessage(code, lang = 'en') {
  return errorMessages[code]?.[lang] || errorMessages[code]?.['en'] || code
}

버킷 용량: 100 토큰
보충 속도: 10 토큰/초

[요청 도착] → 버킷에 토큰 있음? → YES → 토큰 소비, 요청 처리
                                → NO  → 429 응답

class TokenBucket {
  constructor(capacity, refillRate) {
    this.capacity = capacity
    this.tokens = capacity
    this.refillRate = refillRate
    this.lastRefill = Date.now()
  }

  consume() {
    this.refill()
    if (this.tokens > 0) {
      this.tokens--
      return true
    }
    return false
  }

  refill() {
    const now = Date.now()
    const elapsed = (now - this.lastRefill) / 1000
    this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillRate)
    this.lastRefill = now
  }
}

class SlidingWindowLog {
  constructor(windowMs, maxRequests) {
    this.windowMs = windowMs
    this.maxRequests = maxRequests
    this.logs = new Map() // key -> timestamps[]
  }

  isAllowed(key) {
    const now = Date.now()
    const windowStart = now - this.windowMs

    if (!this.logs.has(key)) {
      this.logs.set(key, [])
    }

    const timestamps = this.logs.get(key).filter((ts) => ts > windowStart)
    this.logs.set(key, timestamps)

    if (timestamps.length < this.maxRequests) {
      timestamps.push(now)
      return true
    }

    return false
  }
}

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
X-RateLimit-Reset: 1678886400

---

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1678886400
Retry-After: 30
Content-Type: application/problem+json

{
  "type": "https://api.example.com/errors/rate-limit",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the rate limit. Please retry after 30 seconds."
}

Authorization Code Flow (서버 앱):
1. 사용자 → 인증 서버 (로그인)
2. 인증 서버 → 클라이언트 (Authorization Code)
3. 클라이언트 → 인증 서버 (Code + Client Secret → Access Token)
4. 클라이언트 → 리소스 서버 (Access Token)

Authorization Code + PKCE (SPA/모바일):
1. code_verifier 생성
2. code_challenge = SHA256(code_verifier)
3. 인증 요청에 code_challenge 포함
4. 토큰 교환 시 code_verifier 전송하여 검증

1. Access Token 만료: 15분 (최대 1시간)
2. Refresh Token 만료: 7일 (최대 30일)
3. 서명 알고리즘: RS256 (비대칭) 또는 ES256 권장
4. 민감 정보를 페이로드에 넣지 말 것
5. aud, iss, exp 클레임 반드시 검증
6. httpOnly 쿠키에 저장 (XSS 방지)
7. Token Rotation 적용

# Header 방식 (권장)
GET /api/v1/users HTTP/1.1
Authorization: Bearer <access_token>
X-API-Key: <api_key>

# 절대 URL에 포함하지 말 것
# BAD: /api/v1/users?api_key=abc123

// Express CORS 설정
const cors = require('cors')

app.use(
  cors({
    origin: ['https://app.example.com', 'https://admin.example.com'],
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
    allowedHeaders: ['Content-Type', 'Authorization', 'X-API-Key'],
    credentials: true,
    maxAge: 86400, // Preflight 캐시 24시간
  })
)

// Zod를 사용한 요청 검증
const { z } = require('zod')

const CreateUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  age: z.number().int().min(0).max(150).optional(),
  role: z.enum(['user', 'admin', 'moderator']).default('user'),
})

// 미들웨어
function validate(schema) {
  return (req, res, next) => {
    const result = schema.safeParse(req.body)
    if (!result.success) {
      return res.status(422).json({
        type: 'https://api.example.com/errors/validation',
        title: 'Validation Failed',
        status: 422,
        errors: result.error.issues.map((issue) => ({
          field: issue.path.join('.'),
          code: issue.code,
          message: issue.message,
        })),
      })
    }
    req.body = result.data
    next()
  }
}

app.post('/api/v1/users', validate(CreateUserSchema), createUser)

openapi: 3.1.0
info:
  title: E-Commerce API
  description: E-Commerce REST API
  version: 1.0.0
  contact:
    name: API Team
    email: api@example.com

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /products:
    get:
      operationId: listProducts
      tags: [Products]
      summary: List all products
      parameters:
        - name: category
          in: query
          schema:
            type: string
        - name: sort
          in: query
          schema:
            type: string
            enum: [price, -price, name, -name, created_at]
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Product'
                  pagination:
                    $ref: '#/components/schemas/CursorPagination'
        '429':
          $ref: '#/components/responses/RateLimited'

components:
  schemas:
    Product:
      type: object
      required: [id, name, price]
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
          minLength: 1
          maxLength: 200
        price:
          type: number
          format: decimal
          minimum: 0
        category:
          type: string
        created_at:
          type: string
          format: date-time

    CursorPagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
        has_next:
          type: boolean
        limit:
          type: integer

  responses:
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
        Retry-After:
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

security:
  - BearerAuth: []
  - ApiKeyAuth: []

# OpenAPI Generator로 클라이언트 SDK 생성
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./generated/client

# 서버 스텁 생성
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g nodejs-express-server \
  -o ./generated/server

// Postman Test Script 예시
pm.test('Status code is 200', () => {
  pm.response.to.have.status(200)
})

pm.test('Response has correct structure', () => {
  const json = pm.response.json()
  pm.expect(json).to.have.property('data')
  pm.expect(json.data).to.be.an('array')
  pm.expect(json).to.have.property('pagination')
})

pm.test('Pagination cursor exists', () => {
  const json = pm.response.json()
  if (json.data.length > 0) {
    pm.expect(json.pagination).to.have.property('next_cursor')
  }
})

# Newman으로 CI/CD 파이프라인에서 실행
newman run collection.json \
  --environment production.json \
  --reporters cli,junit \
  --reporter-junit-export results.xml

// Consumer Test (프론트엔드)
const { PactV3 } = require('@pact-foundation/pact')

const provider = new PactV3({
  consumer: 'WebApp',
  provider: 'UserService',
})

describe('User API', () => {
  it('fetches a user by ID', async () => {
    await provider
      .given('user 123 exists')
      .uponReceiving('a request for user 123')
      .withRequest({
        method: 'GET',
        path: '/api/v1/users/123',
        headers: { Accept: 'application/json' },
      })
      .willRespondWith({
        status: 200,
        headers: { 'Content-Type': 'application/json' },
        body: {
          id: 123,
          name: 'John Doe',
          email: 'john@example.com',
        },
      })
      .executeTest(async (mockServer) => {
        const response = await fetch(`${mockServer.url}/api/v1/users/123`, {
          headers: { Accept: 'application/json' },
        })
        expect(response.status).toBe(200)
      })
  })
})

// k6 로드 테스트
import http from 'k6/http'
import { check, sleep } from 'k6'

export const options = {
  stages: [
    { duration: '30s', target: 50 }, // 램프업
    { duration: '1m', target: 100 }, // 유지
    { duration: '30s', target: 0 }, // 램프다운
  ],
  thresholds: {
    http_req_duration: ['p(95)<500'], // 95% 요청 500ms 이내
    http_req_failed: ['rate<0.01'], // 에러율 1% 미만
  },
}

export default function () {
  const res = http.get('https://api.example.com/v1/products?limit=20')

  check(res, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
    'has data array': (r) => JSON.parse(r.body).data.length > 0,
  })

  sleep(1)
}

Stripe의 핵심 설계 원칙:
1. 일관된 리소스 명명 (/v1/customers, /v1/charges, /v1/subscriptions)
2. Expand 파라미터로 관련 리소스 포함
3. 멱등성 키 (Idempotency-Key 헤더)
4. 상세한 에러 응답
5. 자동 페이지네이션 (has_more + starting_after)

# Stripe 스타일 요청
POST /v1/charges HTTP/1.1
Authorization: Bearer sk_test_xxx
Idempotency-Key: unique-request-id-123
Content-Type: application/x-www-form-urlencoded

amount=2000&currency=usd&source=tok_visa

GitHub API 특징:
1. REST + GraphQL 하이브리드
2. 조건부 요청 (ETag, If-None-Match)
3. Link 헤더 페이지네이션
4. Hypermedia (URL 템플릿)
5. Rate Limit 명확한 표시

# GitHub 조건부 요청
GET /repos/octocat/hello-world HTTP/1.1
If-None-Match: "etag-value"

# 304 Not Modified (캐시 사용)
# 또는 200 OK (새 ETag 포함)

Twitter API v2 특징:
1. 필드 선택 (fields 파라미터)
2. Expansion으로 관련 객체 포함
3. 스트리밍 엔드포인트
4. Rate Limit 세분화
5. OAuth2 + App-only Auth

# Twitter 스타일: 필드 선택 + expansion
GET /2/tweets?ids=123,456&tweet.fields=created_at,public_metrics&expansions=author_id&user.fields=username