api-designer

# API Designer

## Overview

이 SKILL은 현대적인 API를 설계, 문서화 및 구현하기 위한 포괄적인 가이드를 제공합니다. REST 및 GraphQL 패러다임을 모두 다루며, 업계의 모범 사례, 명확한 문서화 및 유지보수 가능한 아키텍처를 강조합니다. 확장 가능하고 안전하며 개발자 친화적인 Production-ready API 설계를 위해 이 SKILL을 사용하세요.

## Core Capabilities

### REST API Design
- 적절한 URL 구조를 갖춘 리소스 지향 엔드포인트 설계
- HTTP method 의미론 및 status code 사용
- 일관된 명명 규칙을 적용한 Request/response payload 설계
- Pagination, filtering 및 sorting 전략
- Error handling 및 validation 패턴

### GraphQL API Design
- Type system 및 관계를 포함한 Schema 정의
- 적절한 input type을 사용한 Query 및 mutation 설계
- Resolver 패턴 및 성능 최적화
- Fragment 사용 및 directive 구현
- N+1 문제 방지 전략

### API Documentation
- OpenAPI 3.0 specification 생성
- Swagger UI를 통한 대화형 문서화
- Authentication 및 authorization 문서화
- 다양한 시나리오를 포함한 Example requests/responses
- 사양(Specification)으로부터 코드 생성

### Authentication & Authorization
- OAuth 2.0 flow (authorization code, client credentials, PKCE)
- JWT token 설계, validation 및 rotation
- API key 관리 및 rotation 전략
- Role-based access control (RBAC) 구현
- Rate limiting 및 throttling 패턴

### API Versioning
- URL versioning 및 header-based versioning 전략
- API 릴리스를 위한 Semantic versioning
- Deprecation 계획 및 커뮤니케이션
- Backward compatibility 유지
- Migration 경로 설계

## When to Use This Skill

이 SKILL은 다음과 같은 경우에 사용하세요:
- 새로운 API를 처음부터 설계하거나 기존 엔드포인트를 리팩토링할 때
- 문서화를 위해 OpenAPI/Swagger 사양을 생성할 때
- Authentication 및 authorization flow를 구현할 때
- API versioning 및 deprecation 전략을 계획할 때
- GraphQL schema 및 resolver를 설계할 때
- API governance 및 모범 사례를 확립할 때

## REST API Design Workflow

### Step 1: Identify Resources

API가 노출할 핵심 리소스(Noun)를 식별합니다:

```
Resources: Users, Posts, Comments

Collections:
- GET    /users              (모든 사용자 목록 조회)
- POST   /users              (새 사용자 생성)

Individual Resources:
- GET    /users/{id}         (특정 사용자 조회)
- PUT    /users/{id}         (사용자 교체 - 전체 업데이트)
- PATCH  /users/{id}         (사용자 업데이트 - 일부 업데이트)
- DELETE /users/{id}         (사용자 삭제)

Nested Resources:
- GET    /users/{id}/posts   (사용자의 포스트 조회)
- POST   /users