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, PATCH

• 201 Created : 성공적인 POST

• 204 No Content : 성공적인 DELETE

• 400 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를 사용하여 사양을 생성하고 검증합니다:

코드에서 OpenAPI 사양 생성

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

• 컬렉션에 복수형 명사 사용

• URL nesting을 2단계로 제한

• 적절한 HTTP method 사용

• 정확한 status code 반환

• 일관된 에러 형식 구현

• 컬렉션에 Pagination 추가

• Filtering 및 sorting 포함

• OpenAPI로 문서화

• Authentication 구현

• Rate limiting 추가

GraphQL Schema Design

• 명확한 type hierarchy 정의

• Nullable type을 적절하게 사용

• Pagination(connections) 구현

• Input type을 사용한 mutation 설계

• Payload에 에러 반환

• 설명(Description)으로 스키마 문서화

• Authentication/authorization 구현

• N+1 쿼리 최적화 (DataLoader)

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 사양 생성, 검증 및 문서화 유틸리티