api-design

name	api-design
description	Use when designing API endpoints, reviewing API contracts, adding pagination/filtering, or planning versioning strategy. Do NOT use for API consumption, client-side HTTP, or GraphQL.

API Design Patterns

이 프로젝트들의 API 컨벤션(선택)과 리뷰 기준만 담는다. REST 일반 지식은 모델에 이미 있음.

CRITICAL Rules

1. ALWAYS plural nouns, kebab-case, no verbs — /team-members/:id (예외: actions /orders/:id/cancel)
2. ALWAYS semantic status codes — 200 for everything 금지, created는 201 + Location
3. ALWAYS pagination for list endpoints — unbounded list 금지. Public API는 cursor 기본
4. NEVER expose internal details in errors — stack trace, SQL 쿼리 금지
5. ALWAYS validate at boundaries — 외부 입력·써드파티 응답·env/config 로딩은 검증, 이미 검증된 내부 데이터는 재검증 금지
6. ALWAYS rate limiting — 내부 API 포함
7. 버저닝: URL path (/api/v1/) 방식. breaking change 없이는 새 버전 만들지 않음

Response Envelope (컨벤션)

// Success:    { "data": {...} }  /  { "data": [...], "meta": { "has_next": true, "next_cursor": "..." } }
// Error:      { "error": { "code": "validation_error", "message": "...", "details": [...] } }

• code: machine-readable snake_case / message: human-readable / details: field-level errors
• Public API는 envelope 필수, internal API는 flat 허용

Common Rationalizations

코드 리뷰에서 자주 나오는 변명과 반박. 나 자신의 설계 리뷰에도 적용하라.

변명