| name | api-designer |
| description | OpenAPI/Swagger 사양, 인증 패턴, 버전 관리 전략 및 모범 사례를 사용하여 RESTful 및 GraphQL API를 설계하고 문서화합니다. 사용 사례: (1) API 사양 생성, (2) REST 엔드포인트 설계, (3) GraphQL 스키마 설계, (4) API 인증 및 권한 부여, (5) API 버전 관리 전략, (6) 문서 생성 |
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/{id}/posts (사용자를 위한 포스트 생성)
Step 2: Design URL Structure
RESTful 명명 규칙을 따릅니다:
Best Practices:
- 복수형 명사 사용:
/users, /posts (/user, /post 아님)
- 여러 단어는 하이픈 사용:
/blog-posts (/blogPosts 또는 /blog_posts 아님)
- URL은 소문자로 유지
- Nesting은 최대 2단계로 제한
- Filtering을 위해 query parameter 사용:
/posts?status=published&author=123
Quick Examples:
✅ Good:
GET /users
GET /users/123/posts
GET /posts?published=true&limit=10
❌ Bad:
GET /getUsers
GET /users/123/posts/comments/likes (너무 깊은 nesting)
GET /posts/published (대신 query param 사용)
Step 3: Choose HTTP Methods
작업을 표준 HTTP method에 매핑합니다:
- GET: 리소스 조회 - Safe, idempotent, cacheable
- POST: 새 리소스 생성 - Location header와 함께 201 Created 반환
- PUT: 전체 리소스 교체 - Idempotent, 전체 교체
- PATCH: 부분 업데이트 - 특정 필드만 업데이트
- DELETE: 리소스 제거 - Idempotent, 204 또는 200 반환
Step 4: Design Request/Response Payloads
JSON payload를 일관되게 구성합니다:
Naming Conventions:
- JSON 필드 이름에 camelCase 사용
- 타임스탬프에 ISO 8601 사용 (UTC)
- 접두사가 있는 일관된 ID 형식 사용:
usr_, post_
- 메타데이터 포함:
createdAt, updatedAt
Example Response:
{
"id": "usr_1234567890",
"username": "johndoe",
"email": "john@example.com",
"profile": {
"firstName": "John",
"lastName": "Doe"
},
"createdAt": "2025-10-25T10:30:00Z",
"updatedAt": "2025-10-25T10:30:00Z"
}
Step 5: Implement Error Handling
포괄적인 에러 응답을 설계합니다:
Error Response Format:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": [
{
"field": "email",
"message": "Email format is invalid"
}
],
"requestId": "req_abc123xyz",
"timestamp": "2025-10-25T10:30:00Z"
}
}
Key Status Codes:
200 OK: 성공적인 GET, PUT, PATCH201 Created: 성공적인 POST204 No Content: 성공적인 DELETE400 Bad Request: 유효하지 않은 요청 데이터401 Unauthorized: 인증 정보 누락/유효하지 않음403 Forbidden: 인증되었으나 권한 없음404 Not Found: 리소스가 존재하지 않음422 Unprocessable Entity: Validation 에러429 Too Many Requests: Rate limit 초과500 Internal Server Error: 서버 에러
Step 6: Add Pagination and Filtering
Cursor-Based Pagination (대규모 데이터셋에 권장):
GET /posts?limit=20&cursor=eyJpZCI6MTIzfQ
Response:
{
"data": [...],
"pagination": {
"nextCursor": "eyJpZCI6MTQzfQ",
"hasMore": true
}
}
Offset-Based Pagination (소규모 데이터셋에 적합):
GET /posts?limit=20&offset=40&sort=-createdAt
Response:
{
"data": [...],
"pagination": {
"total": 500,
"limit": 20,
"offset": 40
}
}
상세한 Pagination 전략 및 filtering 패턴은 references/rest_best_practices.md를 참조하세요.
GraphQL API Design Workflow
Step 1: Define Schema Types
도메인을 위한 type definition을 생성합니다:
type User {
id: ID!
username: String!
email: String!
profile: Profile
posts(limit: Int = 10): [Post!]!
createdAt: DateTime!
}
type Post {
id: ID!
title: String!
content: String!
published: Boolean!
author: User!
tags: [String!]!
createdAt: DateTime!
}
Step 2: Design Queries
Filtering을 포함한 조회 작업을 정의합니다:
type Query {
user(id: ID!): User
post(id: ID!): Post
users(
limit: Int = 10
offset: Int = 0
search: String
): UserConnection!
posts(
limit: Int = 10
published: Boolean
authorId: ID
tags: [String!]
): PostConnection!
}
Step 3: Design Mutations
Input type 및 error handling을 포함한 쓰기 작업을 정의합니다:
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
createPost(input: CreatePostInput!): CreatePostPayload!
}
input CreateUserInput {
username: String!
email: String!
password: String!
}
type CreateUserPayload {
user: User
errors: [Error!]
}
전체 GraphQL schema 예시는 examples/graphql_schema.graphql을 참조하세요.
Authentication Patterns
OAuth 2.0 Quick Reference
Authorization Code Flow (백엔드가 있는 웹 앱):
1. client_id, redirect_uri, scope와 함께 /oauth/authorize로 리다이렉트
2. 사용자가 인증하고 권한 부여
3. 리다이렉트를 통해 authorization code 수신
4. /oauth/token에서 코드를 access token으로 교환
5. Authorization header에 access token 사용
Client Credentials Flow (서비스 간 통신):
POST /oauth/token
{
"grant_type": "client_credentials",
"client_id": "CLIENT_ID",
"client_secret": "SECRET"
}
PKCE Flow (모바일/SPA - 퍼블릭 클라이언트에 가장 안전):
1. code_verifier 및 code_challenge 생성
2. code_challenge와 함께 권한 요청
3. code_verifier로 코드를 토큰으로 교환 (client_secret 불필요)
JWT Token Design
Token Structure:
{
"header": { "alg": "RS256", "typ": "JWT" },
"payload": {
"sub": "usr_1234567890",
"iat": 1698336000,
"exp": 1698339600,
"scope": ["read:posts", "write:posts"],
"roles": ["user", "editor"]
}
}
Usage:
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
API Key Authentication
X-API-Key: sk_live_abcdef1234567890
Best Practices:
- 환경별(dev, staging, prod)로 다른 키 사용
- 로테이션을 위해 계정당 여러 키 지원
- Key expiration 및 사용 로그 구현
- 클라이언트 측 코드에 키를 노출하지 않음
Refresh token, MFA 및 보안 모범 사례를 포함한 종합적인 인증 패턴은 references/authentication.md를 참조하세요.
API Versioning Strategies
URL Versioning (권장)
/v1/users
/v2/users
장점: 명확하고 명시적이며, 캐싱 및 라우팅이 쉬움
단점: URL 확산, 여러 코드베이스 관리
Header Versioning
Accept: application/vnd.myapi.v2+json
API-Version: 2
장점: 깔끔한 URL, 동일한 엔드포인트 유지
단점: 덜 가시적이며, 브라우저에서 테스트하기 어려움
When to Version
새로운 버전이 필요한 경우:
- 엔드포인트 또는 필드 삭제
- 필드 유형 또는 이름 변경
- 인증 방법 수정
- 기존 클라이언트 계약(Contract) 위반
버전 관리가 필요 없는 경우:
- 새로운 선택적(Optional) 필드 추가
- 새로운 엔드포인트 추가
- 버그 수정 또는 성능 향상
상세한 Versioning 전략, deprecation 프로세스 및 migration 패턴은 references/versioning-strategies.md를 참조하세요.
OpenAPI Specification
Basic Structure
openapi: 3.0.0
info:
title: My API
version: 1.0.0
description: API description
servers:
- url: https://api.example.com/v1
paths:
/users:
get:
summary: List users
parameters:
- name: limit
in: query
schema:
type: integer
default: 10
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
components:
schemas:
User:
type: object
required:
- username
- email
properties:
id:
type: string
username:
type: string
email:
type: string
format: email
전체 OpenAPI 사양 예시는 examples/openapi_spec.yaml을 참조하세요.
Generating Documentation
Helper script를 사용하여 사양을 생성하고 검증합니다:
python scripts/api_helper.py generate --input api.py --output openapi.yaml
python scripts/api_helper.py validate --spec openapi.yaml
python scripts/api_helper.py docs --spec openapi.yaml --output docs/
Best Practices Summary
Consistency
- 모든 엔드포인트에서 일관된 명명 규칙 사용
- 에러 응답 형식 표준화
- 모든 곳에 동일한 인증 패턴 적용
- 통일된 타임스탬프 형식 사용 (ISO 8601 with UTC)
Security
- Production에서는 항상 HTTPS 사용
- 모든 입력 데이터를 철저히 검증
- 사용자/키/IP별로 Rate limiting 구현
- 모든 엔드포인트에 적절한 인증 사용
- URL이나 로그에 민감한 데이터를 노출하지 않음
- 적절한 CORS 구성 구현
Performance
- 대규모 데이터셋에 Pagination 사용
- 캐싱 헤더(ETag, Cache-Control) 구현
- 압축(gzip) 지원
- 실시간 데이터에 Cursor-based pagination 사용
- Sparse fieldsets을 위한 필드 선택(Field selection) 구현
Documentation
- 모든 엔드포인트를 OpenAPI로 문서화
- Example requests 및 responses 제공
- 에러 코드 및 의미 문서화
- 인증 안내 포함
- 문서를 코드와 동기화된 상태로 유지
Maintainability
- 명확한 deprecation 일정을 가지고 적절하게 API 버전 관리
- 기능을 제거하기 전에 deprecation 경고 제공
- 모든 엔드포인트에 대해 통합 테스트 작성
- API 사용량, 에러 및 성능 모니터링
- 가능한 경우 Backward compatibility 유지
Common Patterns
Health Check
GET /health
Response: { "status": "ok", "timestamp": "2025-10-25T10:30:00Z" }
Batch Operations
POST /users/batch
{
"operations": [
{ "method": "POST", "path": "/users", "body": {...} },
{ "method": "PATCH", "path": "/users/123", "body": {...} }
]
}
Webhooks
POST /webhooks/configure
{
"url": "https://your-app.com/webhook",
"events": ["user.created", "post.published"],
"secret": "webhook_secret_key"
}
Idempotency, long-running operations, file uploads 및 soft deletes를 포함한 추가 패턴은 references/common-patterns.md를 참조하세요.
Quick Reference Checklists
REST Endpoint Design
GraphQL Schema Design
Additional Resources
Comprehensive References
references/rest_best_practices.md - 전체 REST API 패턴, status code 및 구현 세부 정보references/authentication.md - OAuth 2.0, JWT, API keys, MFA 및 보안 모범 사례references/versioning-strategies.md - Versioning 접근 방식, deprecation 및 migration 전략references/common-patterns.md - Health check, webhooks, batch operations 등
Examples
examples/openapi_spec.yaml - 블로그 API를 위한 전체 OpenAPI 3.0 사양examples/graphql_schema.graphql - Query, mutation 및 subscription을 포함한 전체 GraphQL schema
Tools
scripts/api_helper.py - API 사양 생성, 검증 및 문서화 유틸리티
