---

description: "REST API 설계 컨벤션 - 엔드포인트 네이밍, 응답 형태, 쿼리 파라미터, 에러 포맷" paths:

• "**/*.controller.ts"
• "**/*.service.ts"
• "/api/"

---

REST API Design Convention

엔드포인트 네이밍

리소스 중심 (명사)

• 복수형 명사로 컬렉션 표현: /companies, /tags, /groups
• 단건 조회는 ID 파라미터: /companies/:id
• 행위는 HTTP 메서드로 표현, URL 에 동사 넣지 않음

✅ GET    /companies          → 목록 조회
✅ GET    /companies/:id      → 단건 조회
✅ POST   /companies          → 생성
✅ PATCH  /companies/:id      → 부분 수정
✅ DELETE /companies/:id      → 삭제

❌ GET    /getCompanies
❌ POST   /companies/create

하위 리소스

• 소속 관계는 중첩 경로: /companies/:id/groups, /groups/:id/members
• 2단 이상 중첩은 피하고, 필요하면 쿼리 파라미터로 대체

특수 엔드포인트

• 카탈로그/요약: /companies/summary — 랜딩 페이지용 집계 데이터
• 상세 확장: /companies/:id/detail — 단건 + 관계 + 통계 병합
• 이런 엔드포인트는 정적 경로이므로 :id 파라미터 라우트보다 위에 선언

쿼리 파라미터

용도	파라미터	예시
정렬	sort	?sort=follower, ?sort=name
날짜 필터	date	?date=2026-04-06
페이지네이션	page, limit	?page=1&limit=20
필터	필드명 그대로	?companyId=3, ?status=active

• 기본값이 있는 파라미터는 생략 가능하게 설계 (기본 정렬이면 ?sort= 불필요)
• 잘못된 값이 오면 400 BadRequest 로 명확한 에러 메시지 반환

응답 형태

리스트

배열을 직접 반환하거나, 메타데이터가 필요하면 래핑:

// 단순 리스트
[{ "id": 1, "name": "A" }, { "id": 2, "name": "B" }]

// 메타데이터 포함 (페이지네이션 등)
{ "items": [...], "total": 42, "page": 1, "limit": 20 }

단건

객체 직접 반환. 없으면 404.

집계/요약

용도에 맞는 구조 자유롭게. totals, stats 등 명시적 키 사용.

{
  "companies": [...],
  "independentGroups": [...],
  "totals": { "companyCount": 5, "streamerCount": 120 }
}

Mutation 응답

• 생성: 201 + 생성된 리소스 반환
• 수정: 200 + 수정된 리소스 반환
• 삭제: 204 (No Content)
• 비동기 작업 (Discord forward 등): 200 + { "ok": true }

에러 형태

NestJS 기본 에러 포맷을 따른다:

{
  "statusCode": 400,
  "message": "사용자에게 보여줄 수 있는 한국어 메시지",
  "error": "Bad Request"
}

• 에러 메시지는 사용자에게 노출될 수 있다는 전제로 작성
• 내부 구현 세부사항 (스택 트레이스, DB 에러) 노출 금지
• 프로덕션에서는 message 만 전달, 디버깅 정보는 서버 로그에

Cache-Control

읽기 전용 엔드포인트에는 Cache-Control 헤더를 설정한다:

• 자주 변하지 않는 데이터: public, max-age=60~300
• 요약/집계: public, max-age=120
• 실시간 데이터: 설정하지 않음 (기본 no-cache)

버전 관리

• 현재 단일 버전 운영이면 별도 prefix 불필요
• 향후 breaking change 시 /v2/ prefix 도입 검토