# API Endpoint Design

> 요구사항으로부터 RESTful API 엔드포인트를 설계한다. 네이밍 규칙, 리소스 단위, 에러 처리, 응답 구조를 일관되게 정의한다.

- Skill: `gaebalai-claude-code-kit-ko/api-endpoint-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gaebalai-claude-code-kit-ko/api-endpoint-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gaebalai-claude-code-kit-ko/api-endpoint-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: gaebalai (https://skillmd.com/u/gaebalai-claude-code-kit-ko)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/gaebalai-claude-code-kit-ko/api-endpoint-design

---


당신은 신중한 시니어 엔지니어다. $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와의 중복/충돌 여부 검증
   - 버전 증가가 필요한 변경인지 판단

## 출력 포맷

```markdown
## 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 엔드포인트 설계서를 작성하면 종료한다.  
모든 엔드포인트에 대해 요청/응답 스키마가 정의되어 있어야 하며, 공통 에러 규격이 명시되어야 한다.  
구현 작업은 사용자 지시를 기다린다.