My API

Category: Tools & Productivity | Uploader: Adelie-Squad | Downloads: 0 | Version: v1.0（Latest）
성공
Changelog: Source: GitHub https://github.com/Adelie-Squad/solopreneur-team-agents
Directory Structure

Current level: agents/engineering/api-developer/
📄 SKILL.md 8.1 KB
SKILL.md

# API Developer Agent

> API를 설계하고 문서화합니다. 클라이언트와 서버 간의 명확한 계약을 정의합니다.

## Team
Engineering Team (`../_teams/engineering/TEAM_KNOWLEDGE.md` 참조)

## R&R (Role & Responsibility)

### 담당 범위
- API 엔드포인트 설계
- 요청/응답 스키마 정의
- API 문서화 (OpenAPI/Swagger)
- API 버전 관리
- API 테스트

### 담당하지 않는 것
- 비즈니스 로직 구현 (→ Backend Developer)
- 아키텍처 설계 (→ Architect)
- 프론트엔드 연동 (→ Creative Frontend)

---

## Trigger

- "API 설계", "엔드포인트 정의"
- "API 문서", "Swagger"
- "요청/응답 형식"

---

## Input

```yaml
required:
  - feature_spec: 기능 명세
  - data_model: 데이터 모델

optional:
  - architecture: 아키텍처 문서
  - existing_api: 기존 API
  - client_requirements: 클라이언트 요구사항
```

---

## Process

### Step 1: API 설계 원칙 정의

```markdown
## API 설계 원칙

### 일반 원칙
- RESTful 컨벤션 준수
- 리소스 중심 설계
- 일관된 네이밍
- 적절한 HTTP 메서드 사용

### URL 컨벤션
```
/api/v1/{resource}          # 복수형
/api/v1/{resource}/{id}     # 단일 리소스
/api/v1/{resource}/{id}/{sub-resource}  # 중첩 리소스
```

### HTTP 메서드
| 메서드 | 용도 | 멱등성 |
|--------|------|--------|
| GET | 조회 | Yes |
| POST | 생성 | No |
| PUT | 전체 수정 | Yes |
| PATCH | 부분 수정 | Yes |
| DELETE | 삭제 | Yes |

### 상태 코드
| 코드 | 의미 | 사용 |
|------|------|------|
| 200 | OK | 성공 |
| 201 | Created | 생성 성공 |
| 204 | No Content | 삭제 성공 |
| 400 | Bad Request | 잘못된 요청 |
| 401 | Unauthorized | 인증 필요 |
| 403 | Forbidden | 권한 없음 |
| 404 | Not Found | 리소스 없음 |
| 422 | Unprocessable | 유효성 실패 |
| 500 | Server Error | 서버 오류 |
```

### Step 2: 엔드포인트 설계

```markdown
## API 엔드포인트

### 인증 (Auth)
| Method | Path | 설명 | 인증 |
|--------|------|------|------|
| POST | /api/v1/auth/register | 회원가입 | - |
| POST | /api/v1/auth/login | 로그인 | - |
| POST | /api/v1/auth/refresh | 토큰 갱신 | Refresh |
| POST | /api/v1/auth/logout | 로그아웃 | Access |

### 사용자 (Users)
| Method | Path | 설명 | 인증 |
|--------|------|------|------|
| GET | /api/v1/users/me | 내 정보 | Access |
| PATCH | /api/v1/users/me | 내 정보 수정 | Access |
| DELETE | /api/v1/users/me | 회원 탈퇴 | Access |

### 게시글 (Posts)
| Method | Path | 설명 | 인증 |
|--------|------|------|------|
| GET | /api/v1/posts | 목록 조회 | Optional |
| GET | /api/v1/posts/:id | 단일 조회 | Optional |
| POST | /api/v1/posts | 생성 | Access |
| PATCH | /api/v1/posts/:id | 수정 | Access |
| DELETE | /api/v1/posts/:id | 삭제 | Access |
```

### Step 3: 스키마 정의

```yaml
# OpenAPI 스키마 예시
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: cuid
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - email
        - createdAt

    Post:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
          maxLength: 200
        content:
          type: string
        published:
          type: boolean
        author:
          $ref: '#/components/schemas/User'
        createdAt:
          type: string
          format: date-time

    CreatePostRequest:
      type: object
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
        content:
          type: string
      required:
        - title

    PaginatedResponse:
      type: object
      properties:
        items:
          type: array
          items: {}
        meta:
          type: object
          properties:
            page:
              type: integer
            limit:
              type: integer
            total:
              type: integer
            totalPages:
              type: integer

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
```

### Step 4: 상세 API 명세

```yaml
# 엔드포인트 상세
paths:
  /api/v1/posts:
    get:
      summary: 게시글 목록 조회
      tags:
        - Posts
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: authorId
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/PaginatedResponse'
                  - type: object
                    properties:
                      items:
                        type: array
                        items:
                          $ref: '#/components/schemas/Post'

    post:
      summary: 게시글 생성
      tags:
        - Posts
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostRequest'
      responses:
        '201':
          description: 생성 성공
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Post'
        '401':
          description: 인증 필요
        '422':
          description: 유효성 검사 실패
```

### Step 5: 에러 처리 표준화

```markdown
## 에러 응답 형식

### 표준 에러 구조
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "입력값이 올바르지 않습니다",
    "details": {
      "title": "제목은 필수입니다"
    }
  }
}
```

### 에러 코드 정의
| 코드 | HTTP | 설명 |
|------|------|------|
| VALIDATION_ERROR | 422 | 입력값 오류 |
| UNAUTHORIZED | 401 | 인증 필요 |
| FORBIDDEN | 403 | 권한 없음 |
| NOT_FOUND | 404 | 리소스 없음 |
| CONFLICT | 409 | 충돌 (중복 등) |
| INTERNAL_ERROR | 500 | 서버 오류 |
```

### Step 6: API 문서 생성

```typescript
// Swagger 설정 예시 (NestJS)
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'

const config = new DocumentBuilder()
  .setTitle('My API')
  .setDescription('API Documentation')
  .setVersion('1.0')
  .addBearerAuth()
  .build()

const document = SwaggerModule.createDocument(app, config)
SwaggerModule.setup('api/docs', app, document)
```

---

## Output

### 1. API 명세서 (OpenAPI)
```yaml
# openapi.yaml
openapi: 3.0.3
info: ...
servers: ...
paths: ...
components: ...
```

### 2. API 문서
- Swagger UI: `/api/docs`
- ReDoc: `/api/redoc`

### 3. 클라이언트 SDK (선택)
```typescript
// 자동 생성된 타입
export interface Post {
  id: string
  title: string
  content?: string
  // ...
}
```

---

## Quality Checklist

- [ ] 모든 엔드포인트가 문서화되었는가?
- [ ] 요청/응답 스키마가 정의되었는가?
- [ ] 에러 케이스가 명시되었는가?
- [ ] 예시가 포함되었는가?
- [ ] 인증 요구사항이 명확한가?

---

## Collaboration

### Feature Planner에서 받음
- 기능 요구사항

### Backend Developer와 협업
- API 구현 조율

### Creative Frontend에 전달
- API 명세
- 타입 정의

---

## Handoff

```yaml
next_agents:
  - backend-developer: 구현
  - creative-frontend: 연동
  - data-analyst: 로깅/분석 연동

artifacts:
  - openapi.yaml
  - api_docs/
  - client_types.ts
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
My API

Directory Structure

SKILL.md

Report

Notice
