api-endpoint-design

name	api-endpoint-design
description	요구사항으로부터 RESTful API 엔드포인트를 설계한다. 네이밍 규칙, 리소스 단위, 에러 처리, 응답 구조를 일관되게 정의한다.
argument-hint	[요구사항 문서|기존 API 코드|기능 설명] (선택: API 설계 규약 파일)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

요구사항 정의 또는 기능 설명을 기반으로, 일관성 있는 RESTful API 엔드포인트를 설계한다.
리소스 네이밍, URL 구조, HTTP 메서드 선택, 요청/응답 스키마, 에러 처리 전략까지 체계적으로 정의하여 프론트엔드 개발자 및 외부 연동 파트너가 즉시 사용할 수 있는 명세서를 작성한다.
기존 API가 존재하는 경우, 기존 규약과의 정합성도 반드시 검증한다.

입력

• 요구사항 문서, 기능 설명 또는 유스케이스 (필수)
• 기존 API 코드베이스 또는 라우팅 정의 파일 (선택)
• API 설계 규약·스타일 가이드 (선택)
• 도메인 모델 또는 DB 스키마 (선택)
• 정보가 부족하면 사용자에게 질의할 것

절차

1. 기존 API 규약 분석

   • Glob으로 라우팅 정의 파일 검색 (routes.*, router.*, urls.py, controller.* 등)
   • 기존 엔드포인트 네이밍 패턴 분석 (복수형/단수형, kebab-case/snake_case 등)
   • 공통 응답 구조 파악 (엔벨로프 구조 { data, meta, errors } 등)
   • 인증 방식, 버저닝 전략, 헤더 규약 확인

2. 리소스 모델링

   • 요구사항에서 핵심 리소스(명사) 추출
   • RESTful 계층 구조 설계
   • 리소스 관계 정의 (1:N, N:M 등)
   • URL 네스트 깊이는 최대 2단계 원칙 적용
   • 액션성 작업(승인, 취소 등)은:
     • POST /resource/{id}/actions 패턴 또는
     • 명확한 커스텀 서브리소스 방식 중 선택

3. 엔드포인트 상세 설계

   • HTTP 메서드·경로·파라미터 정의
   • 요청 바디 스키마 설계 (필수/선택, 타입, 제약조건)
   • 응답 스키마 설계 (필드, 타입, 구조)
   • 적절한 HTTP 상태 코드 정의:
     • 200 OK
     • 201 Created
     • 204 No Content
     • 400 Bad Request
     • 401 Unauthorized
     • 403 Forbidden
     • 404 Not Found
     • 409 Conflict
     • 422 Unprocessable Entity
     • 500 Internal Server Error

4. 에러 처리 설계

   • 엔드포인트별 발생 가능한 에러 케이스 정의
   • 통합 에러 포맷 정의
   • 필드 단위 검증 오류 구조 설계
   • 인증/인가/레이트리밋 에러 정책 명확화

5. 멱등성·안전성 검토

   • 각 엔드포인트의 멱등성 판단
   • GET/HEAD에 부작용이 없는지 확인
   • PUT vs PATCH 사용 기준 정의
   • 동시성 제어 필요 시 ETag / If-Match 도입 검토

6. 기존 API 정합성 점검

   • 명명 규칙 일치 여부 확인
   • 기존 API와의 중복/충돌 여부 검증
   • 버전 증가가 필요한 변경인지 판단

출력 포맷

## API 엔드포인트 설계서

### 설계 원칙
- **네이밍 규칙**: [예: 복수형 kebab-case `/api/v1/user-profiles`]
- **버저닝 전략**: [예: `/api/v1/` 경로 기반 버저닝]
- **응답 구조**: [예: `{ data, meta, errors }` 엔벨로프 방식]
- **인증 방식**: [예: Bearer Token]
- **인가 정책**: [예: RBAC 기반]

### 리소스 목록

| 리소스 | 설명 | 상위 리소스 |
|--------|------|------------|
| [리소스명] | [설명] | [없음/부모 리소스] |

### 엔드포인트 상세

#### [METHOD] [PATH]

- **설명**: [엔드포인트 목적]
- **인증**: 필요/불필요
- **인가**: [역할/스코프]
- **멱등성**: 있음/없음

**요청 파라미터**

| 이름 | 위치 | 타입 | 필수 | 설명 | 제약조건 |
|------|------|------|------|------|----------|
| [param] | path/query/body | string | Yes | 설명 | maxLength=50 |

**요청 바디 예시**

```json
{
  "example": "value"
}

응답:

상태코드	설명	바디 구조
200	성공	{ data: { ... } }
400	검증 오류	{ errors: [{ field, code, message }] }
404	리소스 없음	{ error: { code, message } }

[메소드] [경로]

(이하 동일하게 반복한다)

공통 에러 응답 규격

{ "error": { "code": "ERROR_CODE", "message": "Human readable message", "details": [ { "field": "email", "code": "INVALID_FORMAT", "message": "Invalid email format" } ] } }

HTTP 상태	에러 코드	사용 조건
400	VALIDATION_ERROR	입력값 오류
401	UNAUTHORIZED	인증 실패
403	FORBIDDEN	권한 부족
404	NOT_FOUND	리소스 없음
409	CONFLICT	상태 충돌

설계 판단 근거

판단 항목	선택	이유
네스트 깊이	최대 2단계	URL 가독성 유지
PUT/PATCH 구분	PUT=전체 교체, PATCH=부분 수정	명확한 의미 분리

기존 API와의 정합성

• 일치 항목: [네이밍/응답 구조 등]
• 차이점: [기존 규약과 다른 부분]
• 버전 영향 여부: [Major/Minor/Patch 필요 여부]

## 안전 유의사항

- 인증 토큰·시크릿의 실제 값은 명세서에 포함하지 않는다.
- 설계 문서 작성만 수행하며 실제 코드 수정은 하지 않는다.
- 기존 API에 Breaking Change가 발생하는 설계일 경우 명확히 경고한다.
- 개인정보를 다루는 엔드포인트는 명확히 표시한다.
- 관리자 전용 API와 일반 사용자 API를 구분한다.

---

## 종료 조건

위 출력 포맷에 맞는 API 엔드포인트 설계서를 작성하면 종료한다.  
모든 엔드포인트에 대해 요청/응답 스키마가 정의되어 있어야 하며, 공통 에러 규격이 명시되어야 한다.  
구현 작업은 사용자 지시를 기다린다.