API 디자인 완전 가이드 — REST·OpenAPI·Versioning·Pagination·Idempotency·Webhook을 2025년 기준으로 한 번에 정리

Level 0: 단일 엔드포인트 + POST로 모든 것
  POST /api
  { "action": "getUser", "id": 1 }

Level 1: 리소스별 URL
  GET /users
  POST /users/createUser (아직 verb in URL)

Level 2: HTTP 메서드 사용
  GET /users/1
  POST /users
  PUT /users/1
  DELETE /users/1

Level 3: HATEOAS (Hypermedia)
  GET /orders/1
  {
    "id": 1, "status": "paid",
    "_links": {
      "self": { "href": "/orders/1" },
      "cancel": { "href": "/orders/1/cancel" }
    }
  }

✅ /users/123/orders
❌ /getUserOrders?userId=123

✅ /users, /orders, /products
❌ /user, /order (단일성/복수성 섞임)

200 OK — 성공
201 Created — 생성됨 (Location 헤더)
202 Accepted — 비동기 시작
204 No Content — 성공, 본문 없음

400 Bad Request — 입력 잘못
401 Unauthorized — 인증 안 됨
403 Forbidden — 권한 없음
404 Not Found
409 Conflict — 상태 충돌
422 Unprocessable Entity — 검증 실패
429 Too Many Requests — Rate limit

500 Internal Server Error
502 Bad Gateway — 업스트림 에러
503 Service Unavailable — 일시 장애
504 Gateway Timeout

{
  "type": "https://example.com/errors/insufficient-funds",
  "title": "Insufficient funds",
  "status": 422,
  "detail": "Account balance $50 is less than required $100",
  "instance": "/accounts/12345/transactions/abc",
  "errors": [
    { "field": "amount", "message": "must be <= balance" }
  ],
  "requestId": "req_abc123"
}

✅ 모든 리소스가 같은 envelope
{
  "data": { ... },
  "meta": { "requestId": "...", "timestamp": "..." }
}

✅ 또는 bare object (일관만 되면 OK)
{ "id": 1, "name": "Alice", ... }

{ "createdAt": "2026-04-15T12:34:56Z" }

// ✅
{ "amount": 10000, "currency": "KRW" }  // 10,000원

// ❌ float은 정확성 문제
{ "amount": 100.50 }

✅ isActive, hasPermission, canEdit
❌ active, permission (명확하지 않음)

// ✅ (미래 확장 여지)
{ "id": "usr_01HX9G7..." }

// ❌ 정수 노출 (시퀀스 유추 가능, 보안)
{ "id": 12345 }

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0
  description: |
    # Overview
    이 API는 ...

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List users
      operationId: listUsers
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - name: cursor
          in: query
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

components:
  schemas:
    User:
      type: object
      required: [id, email]
      properties:
        id: { type: string, pattern: '^usr_' }
        email: { type: string, format: email }
        createdAt: { type: string, format: date-time }

    UserList:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/User' }
        nextCursor: { type: string, nullable: true }

import { z } from 'zod';
import { generateSchema } from '@anatine/zod-openapi';

export const User = z.object({
  id: z.string().startsWith('usr_'),
  email: z.string().email(),
  createdAt: z.string().datetime(),
});

export type User = z.infer<typeof User>;

// OpenAPI spec 생성
const openApiSchema = generateSchema(User);

Spec-first: OpenAPI YAML 먼저 → 서버/클라이언트 생성
  장점: 팀 간 계약, 설계 먼저
  단점: 동기화 번거로움, 런타임 검증 분리

Code-first: 코드에서 스키마 선언 → OpenAPI 생성
  장점: 타입 통일, 런타임 검증 자동
  단점: spec 팀과 협의 지연

https://api.example.com/v1/users
https://api.example.com/v2/users

Accept: application/vnd.example.v1+json

X-API-Version: 2024-12-18

/users?api-version=2

Accept: application/json; version=2

공개 API: URL path (v1, v2) + 날짜 헤더
내부 API: Header 기반, rolling update
모바일: URL path, 오래된 앱도 지원

매일 새 버전 가능 (breaking change 시만 발표)
각 버전은 영원히 유지 (고객 옵트인)
내부적으로 "버전 translator" 운영

GET /users?limit=20&offset=40

{ "data": [...], "total": 1000, "offset": 40, "limit": 20 }

GET /users?limit=20&cursor=eyJpZCI6MTAwfQ==

{
  "data": [...],
  "nextCursor": "eyJpZCI6MTIwfQ==",
  "hasMore": true
}

-- offset 방식 (느림)
SELECT * FROM users ORDER BY id LIMIT 20 OFFSET 100000;

-- keyset (빠름)
SELECT * FROM users WHERE id > 100020 ORDER BY id LIMIT 20;

UI에 "1 2 3 ... 10" 필요 → Offset (큰 데이터엔 비추)
무한 스크롤, API → Cursor
내부 배치 처리, 큰 테이블 → Keyset

사용자가 "결제" 버튼 클릭 → 네트워크 타임아웃 → 재시도
서버는 같은 요청 2번 받음 → 결제 2번 일어남 → 사고

해결: Idempotency Key

POST /charges HTTP/1.1
Idempotency-Key: f8a9b2c3-...-xyz
Content-Type: application/json

{ "amount": 10000, "currency": "KRW" }

1. Idempotency-Key 검사
2. 있으면:
   - 같은 요청 body 이면: 저장된 응답 반환
   - 다른 body 이면: 409 Conflict
3. 없으면: 신규 처리 + 결과 저장 (24시간 TTL)

async function idempotentHandler(req, res) {
  const key = req.headers['idempotency-key'];
  if (!key) return res.status(400).json({ error: 'Idempotency-Key required' });

  // Lock으로 동시 요청 방지
  const lock = await redis.set(`lock:${key}`, '1', 'NX', 'EX', 30);
  if (!lock) {
    // 이미 처리 중 → 잠깐 기다렸다 결과 확인
    await sleep(500);
  }

  const cached = await redis.get(`idempotency:${key}`);
  if (cached) {
    const { bodyHash, response } = JSON.parse(cached);
    const currentHash = hash(req.body);
    if (bodyHash !== currentHash) {
      return res.status(409).json({ error: 'Conflicting request' });
    }
    return res.status(response.status).json(response.body);
  }

  // 실제 처리
  const result = await processPayment(req.body);

  await redis.set(
    `idempotency:${key}`,
    JSON.stringify({ bodyHash: hash(req.body), response: { status: 200, body: result } }),
    'EX',
    86400
  );

  return res.json(result);
}

버킷에 토큰이 일정 속도로 쌓임 (100개/초)
요청은 토큰 1개 소비
토큰 없으면 거부
버스트 허용 (버킷 크기 = 200 → 순간 200 요청 OK)

요청이 큐에 쌓임
일정 속도로 처리 (100개/초)
큐 넘치면 거부
버스트 제어 (일정 속도 보장)

지난 1분간 요청 수 카운트
1000 초과 시 거부
Redis sorted set으로 구현

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1697050800

또는 RFC 9466 (draft):
RateLimit-Limit: 100, 100;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 58

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

Service A → HTTP POST → Service B
이벤트 발생 시 Service B URL로 알림
예: GitHub push → CI, Stripe payment → 내 서버

Header: X-Example-Signature: t=1697050800,v1=abc123...
Body: {"event": "payment.succeeded", ...}

서명 계산: HMAC-SHA256(secret, timestamp + "." + body)

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const [t, v1] = signature.split(',').map(s => s.split('=')[1]);
  const timestamp = parseInt(t);
  if (Math.abs(Date.now()/1000 - timestamp) > 300) return false;  // 5분 이내
  const expected = hmacSha256(secret, `${t}.${body}`);
  return timingSafeEqual(expected, v1);
}

재시도 스케줄 예시:
1분 → 5분 → 15분 → 1시간 → 6시간 → 24시간
최대 3일까지
실패 시 알림 / 대시보드 표시

{ "id": "evt_123...", "event": "payment.succeeded", ... }

Ordered: 순서 보장 (복잡, 속도 느림)
Unordered: 순서 보장 X (빠름, 수신자가 재정렬 or latest-wins)

Accept-Version: 2024-12-18 (헤더) 또는
{"apiVersion": "2024-12-18", "event": "..."}

1. 서명 검증 (무조건 먼저)
2. Timestamp 확인 (5분 이내)
3. Idempotency (이벤트 ID로 중복 체크)
4. 200 즉시 반환 (긴 처리는 큐로)
5. 비동기 처리 (Bull, Celery 등)
6. 실패 시 5xx 반환 → 발신자가 재시도

{
  "specversion": "1.0",
  "type": "com.example.order.created",
  "source": "/orders",
  "id": "evt_abc",
  "time": "2026-04-15T12:00:00Z",
  "datacontenttype": "application/json",
  "data": { "orderId": 123, "amount": 10000 }
}

asyncapi: 3.0.0
info:
  title: Order Service Events
  version: 1.0.0

channels:
  orderCreated:
    address: orders.created
    messages:
      orderCreatedMessage:
        payload:
          type: object
          properties:
            orderId: { type: string }
            amount: { type: integer }

REST (+ OpenAPI):
- 외부 공개 API
- 캐시 중요
- 다양한 클라이언트 (웹, 모바일, 서버)

GraphQL:
- 복잡한 데이터 그래프
- 프론트가 필드 선택 원함
- 모바일 (under-fetching 중요)

gRPC:
- 내부 마이크로서비스
- 고성능 바이너리
- 다양한 언어 간

tRPC:
- 모노레포 TS 풀스택
- 빠른 개발, 타입 자동
- 외부 클라이언트 없음

// typespec
model User {
  id: string;
  email: string;
}

@route("/users")
interface Users {
  @get list(): User[];
  @get read(@path id: string): User;
}

1. Prefix (sk_live_, pk_test_)로 구분
2. 최소 32자 무작위
3. 해시 저장 (비교는 hash == hash)
4. 권한 분리 (read-only, admin 등)
5. 로테이션 쉽게 (old + new 동시 유효 기간)
6. Secrets Scanner 제휴 (GitHub secret scanning)

API Key별 rate limit 다르게
- Free tier: 100/min
- Paid: 1000/min
- Enterprise: 무제한 (단, soft limit 알림)

Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization, Idempotency-Key
Access-Control-Max-Age: 86400

Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Deprecation: true
Link: <https://docs.example.com/v2>; rel="successor-version"