api-design

name	api-design
description	리소스 명명, 상태 코드, 페이지네이션, 필터링, 에러 응답, 버전 관리 및 프로덕션 API를 위한 속도 제한을 포함한 REST API 설계 패턴.
origin	ECC

API 설계 패턴 (API Design Patterns)

일관성 있고 개발자 친화적인 REST API를 설계하기 위한 컨벤션과 모범 사례입니다.

활성화 시점

• 새로운 API 엔드포인트를 설계할 때
• 기존 API 계약을 검토할 때
• 페이지네이션, 필터링 또는 정렬 기능을 추가할 때
• API용 에러 처리를 구현할 때
• API 버전 관리 전략을 계획할 때
• 공개 또는 파트너용 API를 구축할 때

리소스 설계

URL 구조

# 리소스는 명사, 복수형, 소문자, kebab-case를 사용합니다.
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# 관계를 위한 하위 리소스
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# CRUD로 매핑되지 않는 동작 (동사는 드물게 사용)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh

명명 규칙 (Naming Rules)

# 좋음 (GOOD)
/api/v1/team-members          # 여러 단어로 된 리소스에 kebab-case 사용
/api/v1/orders?status=active  # 필터링을 위한 쿼리 파라미터
/api/v1/users/123/orders      # 소유권을 나타내는 중첩 리소스

# 나쁨 (BAD)
/api/v1/getUsers              # URL에 동사 포함
/api/v1/user                  # 단수형 사용 (복수형 권장)
/api/v1/team_members          # URL에 snake_case 사용
/api/v1/users/123/getOrders   # 중첩 리소스에 동사 포함

HTTP 메서드 및 상태 코드

메서드 의미론 (Method Semantics)

메서드	멱등성 (Idempotent)	안전성 (Safe)	용도
GET	예	예	리소스 조회
POST	아니오	아니오	리소스 생성, 동작 트리거
PUT	예	아니오	리소스 전체 교체
PATCH	아니오*	아니오	리소스 일부 업데이트
DELETE	예	아니오	리소스 삭제

*PATCH는 적절한 구현을 통해 멱등성을 가질 수 있습니다.

상태 코드 참조

# 성공 (Success)
200 OK                    — GET, PUT, PATCH (응답 본문 포함 시)
201 Created               — POST (Location 헤더 포함 권장)
204 No Content            — DELETE, PUT (응답 본문 없을 시)

# 클라이언트 에러 (Client Errors)
400 Bad Request           — 유효성 검사 실패, 잘못된 형식의 JSON
401 Unauthorized          — 인증 정보 누락 또는 유효하지 않음
403 Forbidden             — 인증되었으나 권한이 없음
404 Not Found             — 리소스가 존재하지 않음
409 Conflict              — 중복 항목, 상태 충돌
422 Unprocessable Entity  — 의미적으로 유효하지 않음 (JSON은 유효하나 데이터가 잘못됨)
429 Too Many Requests     — 속도 제한 초과

# 서버 에러 (Server Errors)
500 Internal Server Error — 예상치 못한 실패 (상세 내용 노출 금지)
502 Bad Gateway           — 상위 서비스 실패
503 Service Unavailable   — 일시적 과부하, Retry-After 포함 권장

흔한 실수

# 나쁨: 모든 요청에 200 반환
{ "status": 200, "success": false, "error": "Not found" }

# 좋음: HTTP 상태 코드를 의미론적으로 사용
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "User not found" } }

# 나쁨: 유효성 검사 에러에 500 사용
# 좋음: 필드 레벨 상세 내용과 함께 400 또는 422 사용

# 나쁨: 리소스 생성 시 200 사용
# 좋음: Location 헤더와 함께 201 사용
HTTP/1.1 201 Created
Location: /api/v1/users/abc-123

응답 형식

성공 응답

{
  "data": {
    "id": "abc-123",
    "email": "[e-mail]",
    "name": "Alice",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

컬렉션 응답 (페이지네이션 포함)

{
  "data": [
    { "id": "abc-123", "name": "Alice" },
    { "id": "def-456", "name": "Bob" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  },
  "links": {
    "self": "/api/v1/users?page=1&per_page=20",
    "next": "/api/v1/users?page=2&per_page=20",
    "last": "/api/v1/users?page=8&per_page=20"
  

에러 응답

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "invalid_format"
      },
      {
        "field": "age",
        "message": "Must be between 0 and 150",
        "code": "out_of_range"
      }
    ]
  }
}

응답 엔벨로프 (Envelope) 변형

// 옵션 A: data 래퍼가 있는 엔벨로프 (공개 API에 권장)
interface ApiResponse<T> {
  data: T;
  meta?: PaginationMeta;
  links?: PaginationLinks;
}

interface ApiError {
  error: {
    code: string;
    message: string;
    details?: FieldError[];
  };
}

// 옵션 B: 플랫(Flat) 응답 (더 간단하며, 내부 API에서 흔히 사용)
// 성공: 리소스를 직접 반환
// 에러: 에러 객체 반환
// HTTP 상태 코드로 구분

페이지네이션 (Pagination)

오프셋 기반 (단순형)

GET /api/v1/users?page=2&per_page=20

# 구현 예시
SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 20;

장점: 구현이 쉬움, "N 페이지로 이동" 지원 단점: 큰 오프셋(예: OFFSET 100000)에서 느려짐, 동시 삽입 시 데이터 일관성 문제 발생 가능

커서 기반 (확장형)

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

# 구현 예시
SELECT * FROM users
WHERE id > :cursor_id
ORDER BY id ASC
LIMIT 21;  -- has_next 여부를 판단하기 위해 하나 더 가져옴

{
  "data": [...],
  "meta": {
    "has_next": true,
    "next_cursor": "eyJpZCI6MTQzfQ"
  }
}

장점: 위치에 관계없이 일관된 성능, 동시 삽입 시 안정적 단점: 임의의 페이지로 점프 불가, 커서 값이 불투명함

사용 시기 비교

사용 사례	페이지네이션 유형
어드민 대시보드, 작은 데이터셋 (<1만 건)	오프셋
무한 스크롤, 피드, 대용량 데이터셋	커서
공개 API	커서(기본)와 오프셋(선택)
검색 결과	오프셋 (사용자는 페이지 번호를 기대함)

필터링, 정렬 및 검색

필터링 (Filtering)

# 단순 일치
GET /api/v1/orders?status=active&customer_id=abc-123

# 비교 연산자 (대괄호 표기법 사용)
GET /api/v1/products?price[gte]=10&price[lte]=100
GET /api/v1/orders?created_at[after]=2025-01-01

# 여러 값 (쉼표로 구분)
GET /api/v1/products?category=electronics,clothing

# 중첩 필드 (점 표기법 사용)
GET /api/v1/orders?customer.country=US

정렬 (Sorting)

# 단일 필드 (내림차순은 앞에 - 접두사)
GET /api/v1/products?sort=-created_at

# 여러 필드 (쉼표로 구분)
GET /api/v1/products?sort=-featured,price,-created_at

전체 텍스트 검색 (Full-Text Search)

# 검색어 쿼리 파라미터
GET /api/v1/products?q=wireless+headphones

# 특정 필드 검색
GET /api/v1/users?email=alice

스파스 필드셋 (Sparse Fieldsets)

# 지정된 필드만 반환 (페이로드 크기 감소)
GET /api/v1/users?fields=id,name,email
GET /api/v1/orders?fields=id,total,status&include=customer.name

인증 및 인가

토큰 기반 인증

# Authorization 헤더에 Bearer 토큰 사용
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# API 키 (서버 간 통신용)
GET /api/v1/data
X-API-Key: sk_live_abc123

인가 패턴 (Authorization Patterns)

// 리소스 레벨: 소유권 확인
app.get("/api/v1/orders/:id", async (req, res) => {
  const order = await Order.findById(req.params.id);
  if (!order) return res.status(404).json({ error: { code: "not_found" } });
  if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
  return res.json({ data: order });
});

// 역할 기반: 권한 확인
app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
  await User.delete(req.params.id);
  return res.status(204).send();
});

속도 제한 (Rate Limiting)

헤더 정보

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

# 한도 초과 시
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

속도 제한 등급 (Rate Limit Tiers)

등급	한도	윈도우	사용 사례
익명	30회/분	IP당	공개 엔드포인트
인증됨	100회/분	사용자당	표준 API 액세스
프리미엄	1000회/분	API 키당	유료 API 플랜
내부용	10000회/분	서비스당	서비스 간 통신

버전 관리 (Versioning)

URL 경로 버전 관리 (권장)

/api/v1/users
/api/v2/users

장점: 명시적임, 라우팅이 쉬움, 캐시 가능 단점: 버전 간 URL이 변경됨

헤더 버전 관리

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

장점: 깔끔한 URL 단점: 테스트가 더 어려움, 잊어버리기 쉬움

버전 관리 전략

1. /api/v1/로 시작 — 필요할 때까지 버전을 올리지 마세요.
2. 최대 2개의 활성 버전(현재 + 이전)을 유지하세요.
3. 지원 중단(Deprecation) 타임라인:
   - 지원 중단 예고 (공개 API의 경우 6개월 전 공지)
   - Sunset 헤더 추가: Sunset: Sat, 01 Jan 2026 00:00:00 GMT
   - 지원 종료 날짜 이후에는 410 Gone 반환
4. 하위 호환되는 변경은 새 버전이 필요하지 않습니다:
   - 응답에 새로운 필드 추가
   - 새로운 선택적 쿼리 파라미터 추가
   - 새로운 엔드포인트 추가
5. 하위 호환되지 않는 변경은 새 버전이 필요합니다:
   - 필드 제거 또는 이름 변경
   - 필드 타입 변경
   - URL 구조 변경
   - 인증 방식 변경

구현 패턴

TypeScript (Next.js API 라우트)

import { z } from "zod";
import { NextRequest, NextResponse } from "next/server";

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

export async function POST(req: NextRequest) {
  const body = await req.json();
  const parsed = createUserSchema.safeParse(body);

  if (!parsed.success) {
    return NextResponse.json({
      error: {
        code: "validation_error",
        message: "Request validation failed",
        details: parsed.error.issues.map(i => ({
          field: i.path.join("."),
          message: i.,
          : i.,
        })),
      },
    }, { :  });
  }

   user =  (parsed.);

   .(
    { : user },
    {
      : ,
      : { :  },
    },
  );
}

Python (Django REST Framework)

from rest_framework import serializers, viewsets, status
from rest_framework.response import Response

class CreateUserSerializer(serializers.Serializer):
    email = serializers.EmailField()
    name = serializers.CharField(max_length=100)

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "email", "name", "created_at"]

class UserViewSet(viewsets.ModelViewSet):
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]

    def get_serializer_class(self):
        if self.action == "create":
            return CreateUserSerializer
        return UserSerializer

    def create(self, request):
        serializer = CreateUserSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = UserService.create(**serializer.validated_data)
        return Response(
            {"data": UserSerializer(user).data},
            status=status.HTTP_201_CREATED,
            headers={"Location": f"/api/v1/users/{user.id}"},
        )

Go (net/http)

func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")
        return
    }

    if err := req.Validate(); err != nil {
        writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
        return
    }

    user, err := h.service.Create(r.Context(), req)
    if err != nil {
        switch {
        case errors.Is(err, domain.ErrEmailTaken):
            writeError(w, http.StatusConflict, "email_taken", "Email already registered")
        default:
            writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
        }
        return
    }

    w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
    writeJSON(w, http.StatusCreated, map[string]any{"data": user})
}

API 설계 체크리스트

새로운 엔드포인트를 출시하기 전에 확인하세요:

• 리소스 URL이 명명 규칙을 따름 (복수형, kebab-case, 동사 없음)
• 올바른 HTTP 메서드 사용 (조회는 GET, 생성은 POST 등)
• 적절한 상태 코드 반환 (모든 요청에 200 반환 금지)
• 스키마를 통한 입력 유효성 검사 (Zod, Pydantic, Bean Validation 등)
• 에러 응답이 코드와 메시지가 포함된 표준 형식을 따름
• 목록 엔드포인트에 페이지네이션 구현 (커서 또는 오프셋)
• 인증 요구 (또는 명시적으로 공개 엔드포인트로 표시)
• 인가 확인 (사용자가 자신의 리소스에만 액세스할 수 있는지 확인)
• 속도 제한 구성
• 응답에 내부 정보(스택 트레이스, SQL 에러 등) 노출 없음
• 기존 엔드포인트와 일관된 명명 규칙 유지 (camelCase 대 snake_case)
• 문서화 (OpenAPI/Swagger 사양 업데이트)