API 도입이 정체될 때 /platform-product-manager가 개발자 경험을 정리해 플랫폼 참여도를 높입니다. — Claude Skill

---

title: 섹션 구성

1. API 설계(api)

영향도: 매우 높음 설명: API 설계 원칙, 표준, 패턴입니다. 개발자 경험의 기반입니다.

2. 개발자 경험(dx)

영향도: 매우 높음 설명: 개발자 온보딩, 가치 도달 시간, 전체 경험입니다. 가장 중요한 차별화 요소입니다.

3. 문서 전략(docs)

영향도: 높음 설명: 개발자 문서 구조, 품질 기준, 유지관리입니다. 문서는 제품입니다.

4. SDK 전략(sdk)

영향도: 높음 설명: SDK와 라이브러리 전략, 언어 우선순위, 유지관리 접근 방식입니다.

5. 버전 관리 및 지원 중단(versioning)

영향도: 높음 설명: API 버전 관리 전략, 호환성 깨는 변경 관리, 지원 중단 예고 프로세스입니다.

6. 개발자 커뮤니티(community)

영향도: 중상 설명: 개발자 커뮤니티 구축, 참여, 생태계 개발입니다.

7. 통합 마켓플레이스(marketplace)

영향도: 중간 설명: 파트너 통합, 마켓플레이스 전략, 생태계 확장입니다.

8. 플랫폼 지표(metrics)

영향도: 매우 높음 설명: 플랫폼 상태 지표, 개발자 성공 측정, 데이터 기반 개선입니다.

---

title: API 설계 원칙 impact: CRITICAL tags: api, design, rest, graphql, standards

API 설계 원칙

영향도: 매우 높음

API는 개발자를 위한 사용자 인터페이스입니다. 시각적 UI를 설계할 때와 같은 엄격함과 세심함으로 설계하세요.

API 설계의 다섯 기둥

리소스 이름 규칙

좋은 리소스 이름:

GET    /users                    # 사용자 목록
GET    /users/{id}               # 단일 사용자 조회
POST   /users                    # 사용자 생성
PATCH  /users/{id}               # 사용자 업데이트
DELETE /users/{id}               # 사용자 삭제

GET    /users/{id}/orders        # 사용자의 주문(중첩 리소스)
GET    /orders/{id}              # ID로 주문 조회(최상위 접근)

나쁜 리소스 이름:

GET    /getUsers                 # URL에 동사 사용
GET    /user/{id}                # 단수/복수 불일치
POST   /users/create             # 중복된 동작 표현
GET    /users/{id}/getOrders     # 중첩 리소스에 동사 사용
GET    /api/v1/Users             # 대소문자 규칙 불일치

HTTP 메서드 매트릭스

*PATCH도 신중하게 설계하면 멱등적으로 만들 수 있습니다.

응답 래퍼 패턴

일관된 응답 구조:

{
  "data": {
    "id": "usr_123",
    "email": "[email protected]",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

페이지네이션이 있는 목록 응답:

{
  "data": [
    { "id": "usr_123", "email": "[email protected]" },
    { "id": "usr_456", "email": "[email protected]" }
  ],
  "meta": {
    "total_count": 150,
    "page": 1,
    "per_page": 20,
    "has_more": true
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}

오류 응답 설계

좋은 오류 응답:

{
  "error": {
    "code": "validation_error",
    "message": "요청 본문에 유효하지 않은 필드가 포함되어 있습니다",
    "details": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "이메일은 유효한 이메일 주소 형식이어야 합니다"
      },
      {
        "field": "amount",
        "code": "out_of_range",
        "message": "금액은 1에서 10000 사이여야 합니다"
      }
    ],
    "doc_url": "https://docs.example.com/errors/validation_error",
    "request_id": "req_abc123"
  }
}

나쁜 오류 응답:

{
  "error": "문제가 발생했습니다"
}

{
  "success": false,
  "message": "유효하지 않은 입력입니다"
}

{
  "code": 400
}

ID 설계 원칙

접두사 ID 패턴(권장):

usr_2cDnPmQTz4         # 사용자
ord_8bKmLpNwQr         # 주문
txn_3gHjRsTvWx         # 거래
api_key_4nLmOpQrSt     # API 키

요청 매개변수 지침

필터링/옵션에는 쿼리 매개변수:

GET /users?status=active&created_after=2024-01-01&limit=50
GET /orders?customer_id=cust_123&include=line_items

리소스 식별에는 경로 매개변수:

GET /users/{user_id}/orders/{order_id}

복잡한 데이터에는 요청 본문:

POST /orders
{
  "customer_id": "cust_123",
  "line_items": [
    { "product_id": "prod_456", "quantity": 2 }
  ]
}

멱등성 설계

멱등성 키 패턴:

POST /charges
Idempotency-Key: abc123-unique-key

{
  "amount": 1000,
  "currency": "usd"
}

서버 처리:

1. 멱등성 키가 있는지 확인
2. 있으면 캐시된 응답 반환
3. 새 키이면 요청을 처리하고 응답을 캐시

필드 이름 표준

타임스탬프 필드:

{
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-16T14:22:00Z",
  "deleted_at": null
}

안티패턴

• 일관되지 않은 이름 — created_at, createdAt, CreateDate를 섞어 사용
• URL의 동사 — /users/{id} 대신 /users/getById
• HTTP 의미 무시 — 읽기에 POST를 쓰거나 변경에 GET을 사용
• 새는 추상화 — API 구조에 데이터베이스 스키마를 노출
• 버전 관리 전략 없음 — 버전 통제 없이 호환성을 깨는 변경 배포
• 요청 ID 누락 — 시스템 전체에서 요청을 추적할 방법 없음
• 불투명한 오류 — 실행 가능한 세부 정보 없는 일반 오류 메시지
• 일관되지 않은 null 처리 — 어떤 때는 생략하고 어떤 때는 null 반환

---

title: API 보안 및 인증 impact: CRITICAL tags: security, authentication, authorization, api-keys, oauth

API 보안 및 인증

영향도: 매우 높음

API에서 보안은 타협할 수 없습니다. 한 번의 침해는 개발자 신뢰를 영구적으로 무너뜨립니다.

인증 방식 비교

API 키 설계

좋은 API 키 형식:

{prefix}_live_{random_string}   (시크릿 키, 프로덕션)
{prefix}_test_{random_string}   (시크릿 키, 테스트)
pk_live_{random_string}         (게시 가능 키, 프로덕션)
pk_test_{random_string}         (게시 가능 키, 테스트)

예시: acme_live_a1b2c3d4e5f6g7h8i9j0

키 구성 요소:

• 접두사: 타입 식별자(sk_, pk_)
• 환경: live 또는 test
• 무작위 문자열: 높은 엔트로피, 24-32자

API 키 관리:

OAuth 2.0 구현

일반 OAuth 흐름:

인증 코드 흐름:

┌──────────┐                              ┌──────────┐
│ 클라이언트│                              │ 인증     │
│ 앱       │                              │ 서버     │
└────┬─────┘                              └────┬─────┘
     │                                          │
     │ 1. /authorize로 리디렉션                 │
     │ ────────────────────────────────────────►│
     │                                          │
     │ 2. 사용자가 인증                         │
     │                                          │
     │ 3. 인증 코드와 함께 리디렉션             │
     │ ◄────────────────────────────────────────│
     │                                          │
     │ 4. 코드를 토큰으로 교환                  │
     │ ────────────────────────────────────────►│
     │                                          │
     │ 5. 액세스 + 리프레시 토큰 반환           │
     │ ◄────────────────────────────────────────│
     │                                          │

토큰 모범 사례

액세스 토큰 설계:

리프레시 토큰 설계:

범위와 권한

좋은 범위 설계:

read:users          # 사용자 데이터 읽기
write:users         # 사용자 생성/업데이트
delete:users        # 사용자 삭제

read:orders         # 주문 읽기
write:orders        # 주문 생성
admin:orders        # 주문 전체 접근

read:*              # 모든 리소스 읽기
admin:*             # 전체 접근

범위 계층:

admin:users
    │
    ├── write:users
    │       │
    │       └── read:users
    │
    └── delete:users

속도 제한 보안

속도 제한 기준:

속도 제한 헤더:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

HTTP/1.1 429 Too Many Requests
Retry-After: 60

웹훅 보안

웹훅 서명 검증:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(f"sha256={expected}", signature)

# 사용 예
is_valid = verify_webhook(
    payload=request.body,
    signature=request.headers['X-Signature'],
    secret=webhook_secret
)

웹훅 보안 체크리스트:

• 모든 웹훅에 HMAC 서명
• 타임스탬프 검증(재전송 공격 방지)
• HTTPS 엔드포인트만 허용
• 지수 백오프로 재시도
• 멱등성 지원
• IP 허용 목록 옵션

보안 헤더

필수 응답 헤더:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Content-Security-Policy: default-src 'none'
Cache-Control: no-store

입력 검증

모든 입력 검증:

검증 오류 응답:

{
  "error": {
    "code": "validation_error",
    "message": "요청 검증에 실패했습니다",
    "details": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "유효한 이메일 주소여야 합니다"
      }
    ]
  }
}

민감 데이터 처리

응답에 절대 노출하지 말 것:

• 전체 신용카드 번호
• 비밀번호 또는 비밀번호 해시
• API 시크릿 키
• 정보를 노출하는 내부 ID
• 명시적으로 요청되지 않은 개인정보

마스킹 패턴:

{
  "card": {
    "last4": "4242",
    "brand": "visa",
    "exp_month": 12,
    "exp_year": 2025
  }
}

보안 로깅

보안을 위해 로깅할 항목:

안티패턴

• URL에 API 키 포함 — 쿼리 매개변수는 로깅, 캐싱, 노출됨
• 속도 제한 없음 — 서비스 거부 취약점
• 장수명 토큰 — 침해 노출 시간이 길어짐
• 응답에 시크릿 포함 — API 응답에서 키 노출
• HTTP 허용 — HTTPS 강제 없음
• 키 순환 없음 — 유출에 대응할 수 없음
• 하드코딩된 시크릿 — 코드/설정에 키 포함
• 지나치게 넓은 범위 — 전부 아니면 전무식 권한
• 감사 로그 누락 — 인시던트를 조사할 수 없음
• 클라이언트 입력 신뢰 — 서버 측 검증 없음

---

title: 웹훅 및 이벤트 기반 API impact: HIGH tags: webhooks, events, async, real-time, notifications

웹훅 및 이벤트 기반 API

영향도: 높음

웹훅은 API를 요청-응답 방식에서 실시간 플랫폼으로 바꿉니다. 개발자가 반응형 통합을 만드는 핵심 방식입니다.

웹훅과 폴링 비교

이벤트 이름 규칙

좋은 이벤트 이름:

{resource}.{action}

customer.created
customer.updated
customer.deleted

order.placed
order.fulfilled
order.cancelled

payment.succeeded
payment.failed
payment.refunded

subscription.created
subscription.upgraded
subscription.cancelled

이벤트 이름 규칙:

• resource.action 형식 사용
• 완료된 동작에는 과거형 사용
• 소문자와 점 구분 사용
• 구체적으로 작성(일반적인 data.changed 지양)

웹훅 페이로드 구조

완전한 웹훅 페이로드:

{
  "id": "evt_1NqINN2eZvKYlo2C4LsR",
  "object": "event",
  "type": "customer.created",
  "created": 1705312200,
  "api_version": "2024-01-01",
  "data": {
    "object": {
      "id": "cus_NqINNKdSBqHhzG",
      "object": "customer",
      "email": "[email protected]",
      "name": "김지현",
      "created": 1705312200
    },
    "previous_attributes": null
  },
  "request": {
    "id": "req_abc123",
    "idempotency_key": "key_xyz789"
  },
  "livemode": true
}

필수 페이로드 필드:

웹훅 전달 보장

전달 의미론:

재시도 전략

지수 백오프 일정:

최대 재시도 이후:

• 웹훅을 실패로 표시
• 개발자에게 이메일 알림
• 대시보드에서 수동 재시도 제공

웹훅 서명 검증

서명 헤더 형식:

POST /webhook HTTP/1.1
Content-Type: application/json
X-Signature: t=1705312200,v1=5257a869e...
X-Webhook-ID: wh_1NqINN2eZvKYlo2C

{webhook payload}

검증 단계:

import hmac
import hashlib
import time

def verify_signature(payload, header, secret):
    # 서명 헤더 파싱
    parts = dict(p.split('=') for p in header.split(','))
    timestamp = int(parts['t'])
    signature = parts['v1']

    # 타임스탬프 확인(재전송 공격 방지)
    if abs(time.time() - timestamp) > 300:  # 5분 허용 오차
        return False

    # 예상 서명 계산
    signed_payload = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    # 비교(타이밍 공격 방지)
    return hmac.compare_digest(expected, signature)

웹훅 엔드포인트 설정

제공할 설정 옵션:

웹훅 대시보드 기능

필수 대시보드 뷰:

웹훅
├── 엔드포인트
│   ├── 엔드포인트 생성
│   ├── 엔드포인트 편집
│   └── 엔드포인트 삭제
│
├── 이벤트 로그
│   ├── 이벤트 타입으로 필터링
│   ├── 상태로 필터링
│   ├── 페이로드 보기
│   └── 수동 재시도
│
├── 테스트
│   ├── 테스트 이벤트 전송
│   └── 로컬 테스트 설정
│
└── 지표
    ├── 전달률
    ├── 평균 지연 시간
    └── 실패 이유

웹훅 처리 모범 사례

좋은 웹훅 핸들러:

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    payload = request.get_data(as_text=True)
    sig_header = request.headers.get('X-Signature')

    # 1. 서명 검증
    if not verify_signature(payload, sig_header, webhook_secret):
        return '유효하지 않은 서명', 400

    event = json.loads(payload)

    # 2. 멱등성 확인(이미 처리했는가?)
    if already_processed(event['id']):
        return 'OK', 200

    # 3. 핸들러로 라우팅
    try:
        if event['type'] == 'customer.created':
            handle_customer_created(event['data']['object'])
        elif event['type'] == 'payment.succeeded':
            handle_payment_succeeded(event['data']['object'])
        # ... 추가 핸들러

        # 4. 처리 완료 표시
        mark_processed(event['id'])

    except Exception as e:
        # 앱 오류 때문에 재시도가 반복되지 않도록 로그만 남기고 200 반환
        log_error(e, event)

    return 'OK', 200

핸들러 규칙:

1. 빠르게 응답(< 30초)
2. 무거운 작업은 비동기로 처리
3. 멱등적으로 설계
4. 성공 시 2xx 반환
5. 재시도시키고 싶은 문제에만 4xx/5xx 반환

이벤트 순서

이벤트는 순서가 뒤바뀌어 도착할 수 있습니다:

실제 순서:          전달 순서(가능):
1. order.created    1. order.created
2. order.updated    2. order.fulfilled
3. order.fulfilled  3. order.updated

순서가 뒤바뀐 이벤트 처리:

• created 타임스탬프로 순서 판단
• 버전/시퀀스 번호 포함
• 순서에 의존하지 않는 핸들러 설계
• 상태 비교에는 data.previous_attributes 사용

웹훅 테스트

로컬 개발 옵션:

테스트 이벤트 페이로드:

{
  "id": "evt_test_123",
  "type": "customer.created",
  "data": {
    "object": {
      "id": "cus_test_123",
      "email": "[email protected]"
    }
  },
  "livemode": false
}

이벤트 문서화

각 이벤트 타입을 문서화:

# customer.created

새 고객이 생성될 때 발생합니다.

## 페이로드

```json
{
  "type": "customer.created",
  "data": {
    "object": {
      "id": "cus_123",
      "email": "[email protected]",
      "name": "김지현",
      "created": 1705312200
    }
  }
}

트리거

• API: POST /v1/customers
• 대시보드: 고객 생성
• 체크아웃: 체크아웃 중 새 고객 생성

관련 이벤트

• customer.updated
• customer.deleted

### 안티패턴

- **서명 검증 없음** — 누구나 웹훅을 위조할 수 있음
- **동기 처리** — 느린 핸들러가 타임아웃을 유발
- **멱등성 없음** — 중복 이벤트가 중복 동작을 유발
- **앱 버그에 오류 반환** — 무한 재시도를 유발
- **이벤트 로그 없음** — 전달 문제를 디버깅할 수 없음
- **이벤트 누락** — 중요한 상태 변화를 노출하지 않음
- **테스트 모드 없음** — 개발하기 어려움
- **수동 재시도 없음** — 실패에서 복구할 수 없음
- **문서화되지 않은 이벤트** — 개발자가 무엇을 기대해야 하는지 모름
- **페이로드 호환성 파괴** — 버전 관리 없이 이벤트 구조 변경

---

title: 개발자 커뮤니티 구축 impact: MEDIUM-HIGH tags: community, devrel, developer-relations, ecosystem

개발자 커뮤니티 구축

영향도: 중상

활발한 개발자 커뮤니티는 방어력입니다. 커뮤니티는 피드백을 제공하고, 콘텐츠를 만들고, 질문에 답하며, 도입을 확산시킵니다.

커뮤니티 성숙 단계

커뮤니티 플랫폼 선택

커뮤니티 참여 퍼널

인지                         100% ────────────────────────────────
    │
    ▼
커뮤니티 가입                 20% ────────────────
    │
    ▼
눈팅 회원 → 독자              15% ──────────────
    │
    ▼
질문 작성                      5% ─────
    │
    ▼
답변 작성                      2% ──
    │
    ▼
챔피언                         0.5% ─

개발자 챔피언 프로그램

챔피언 등급:

제공할 챔피언 혜택:

• 기능 조기 접근
• 팀과 연결되는 전용 Slack/Discord
• 컨퍼런스 발표 기회
• 콘텐츠 공동 마케팅
• 굿즈와 인정
• 로드맵 의견 반영

커뮤니티 콘텐츠 유형

커뮤니티 응답 SLA

커뮤니티 상태 지표

개발자 이벤트 전략

투자 수준별 이벤트 유형:

피드백 루프 구조

┌─────────────────────────────────────────────────┐
│              커뮤니티 피드백                    │
└──────────────────────┬──────────────────────────┘
                       │
         ┌─────────────┴─────────────┐
         ▼                           ▼
┌─────────────────┐        ┌─────────────────┐
│ 분류/태그 지정  │        │ 응답            │
│  - 버그         │        │  - 확인         │
│  - 기능         │        │  - 일정         │
│  - 질문         │        │  - 우회책       │
└────────┬────────┘        └─────────────────┘
         │
         ▼
┌─────────────────┐
│ 제품 입력       │
│  - 우선순위화   │
│  - 로드맵       │
│  - 루프 닫기    │
└─────────────────┘

부정적 피드백 처리

응답 프레임워크(HEARD):

커뮤니티 운영 지침

정해야 할 규칙:

1. 존중하고 포용적으로 대화
2. 주제에서 벗어나지 않기
3. 스팸 또는 자기 홍보 금지
4. 질문하기 전에 검색
5. 적절한 채널 사용
6. 인증 정보/키 공유 금지

집행 단계:

1. 친절한 안내
2. 공식 경고
3. 임시 음소거(24시간)
4. 더 긴 정지(7일)
5. 영구 차단

개발자 옹호와 개발자 지원

안티패턴

• 유령 도시 — 커뮤니티는 있지만 팀 참여가 없음
• 기업식 말투 — 개발자 공간에서 마케팅 언어 사용
• 비판 무시 — 부정적 피드백 삭제
• 과도한 약속 — 제품 관리자 정렬 없이 기능 약속
• 챔피언 방치 — 핵심 기여자를 키우지 않음
• 지표 집착 — 건강성보다 허영 지표 최적화
• 일방 방송 — 참여 없이 발표만 함
• 느린 응답 — 질문이 답 없이 방치됨
• 에스컬레이션 경로 없음 — 커뮤니티가 의사결정자에게 닿을 수 없음

---

title: 개발자 문서 전략 impact: HIGH tags: docs, documentation, reference, guides

개발자 문서 전략

영향도: 높음

문서는 제품입니다. 뛰어난 문서는 지원 부담을 줄이고, 활성화를 높이며, 가장 좋은 마케팅 자산이 됩니다.

문서 피라미드

                    ┌─────────────────┐
                    │    튜토리얼     │  ← "배우고 싶다"
                    │  학습 중심
                    ├─────────────────┤
                    │  방법 가이드    │  ← "완수하고 싶다"
                    │  작업 중심
                    ├─────────────────┤
                    │    레퍼런스     │  ← "찾아보고 싶다"
                    │  정보 중심
                    ├─────────────────┤
                    │     설명        │  ← "이해하고 싶다"
                    │  이해 중심
                    └─────────────────┘

문서 유형 매트릭스

API 레퍼런스 구조

좋은 API 레퍼런스 페이지:

# 고객 생성

새 고객 객체를 생성합니다.

## 엔드포인트

POST /v1/customers

## 인증

`customers:write` 범위가 있는 Bearer 토큰이 필요합니다.

## 요청 본문

| 매개변수 | 타입 | 필수 | 설명 |
|-----------|------|----------|-------------|
| email | string | 예 | 고객 이메일 주소 |
| name | string | 아니요 | 고객 전체 이름 |
| metadata | object | 아니요 | 사용자 지정 데이터를 위한 키-값 쌍 |

## 요청 예시

```bash
curl https://api.example.com/v1/customers \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "김지현"}'

응답

{
  "id": "cus_123abc",
  "object": "customer",
  "email": "[email protected]",
  "name": "김지현",
  "created_at": "2024-01-15T10:30:00Z"
}

오류

### 코드 샘플 표준

**다중 언어 탭:**

```markdown
[curl] [Python] [Node.js] [Ruby] [Go] [Java]

```python
import example

client = example.Client("sk_test_...")

customer = client.customers.create(
    email="[email protected]",
    name="김지현"
)

print(customer.id)

**코드 샘플 요구 사항:**
- 완전하고 실행 가능해야 함
- 현실적인 값을 사용
- 응답 처리를 보여줌
- 관련된 경우 오류 처리를 포함
- 원시 HTTP가 아니라 SDK 규칙을 사용

### 문서 사이트 아키텍처

docs.example.com/ ├── /quickstart # 5분 가이드 ├── /tutorials/ # 학습 경로 │ ├── /basics │ └── /advanced ├── /guides/ # 방법 가이드 │ ├── /authentication │ ├── /webhooks │ └── /error-handling ├── /api/ # API 레퍼런스 │ ├── /customers │ ├── /orders │ └── /webhooks ├── /sdks/ # SDK 문서 │ ├── /python │ ├── /node │ └── /go ├── /concepts/ # 심층 설명 │ ├── /authentication │ └── /rate-limiting ├── /changelog # 버전 이력 └── /support # 도움말 리소스

### 문서 품질 체크리스트

**모든 페이지에 있어야 할 것:**

- [ ] 명확한 제목과 목적
- [ ] 작동하는 코드 예시
- [ ] 코드 블록 복사 버튼
- [ ] 마지막 업데이트 날짜
- [ ] 피드백 메커니즘
- [ ] 관련 페이지 링크
- [ ] 검색 노출성

**모든 코드 샘플이 갖춰야 할 것:**

- [ ] 테스트되고 작동함
- [ ] 최신 SDK 버전 사용
- [ ] 필요한 import 포함
- [ ] 완전한 맥락 제시
- [ ] 일반 오류 처리

### 검색과 탐색

**좋은 검색 기능:**
- 전체 문서 대상 전문 검색
- 검색 제안/자동완성
- 문서 유형별 필터(가이드, 레퍼런스 등)
- 최근 검색
- 인기 검색

**좋은 탐색:**
- 계층 구조가 있는 고정 사이드바
- 이동 경로
- 이전/다음 페이지 링크
- 페이지 내 목차
- 관련 페이지

### 문서 유지관리

**버전 동기화:**

| 구성 요소 | 업데이트 트리거 | 담당 |
|-----------|----------------|-------|
| API 레퍼런스 | API 변경 | 엔지니어링 |
| 코드 샘플 | SDK 릴리스 | 개발자 관계/개발자 경험 |
| 가이드 | 기능 출시 | 제품 |
| 변경 로그 | 모든 릴리스 | 릴리스 관리자 |

**문서 부채 신호:**
- 문서를 언급하는 지원 티켓
- 개발자 불만
- 오래된 코드 샘플
- 문서에 없는 기능
- 깨진 링크

### 문서 지표

| 지표 | 측정 대상 | 목표 |
|--------|------------------|--------|
| **페이지 조회수** | 도달 범위 | 상승 추세 |
| **페이지 체류 시간** | 참여 | 2-5분 |
| **이탈률** | 관련성 | < 50% |
| **검색 → 결과 없음** | 공백 | < 5% |
| **지원 회피** | 효과 | > 70% |
| **피드백 점수** | 품질 | > 4/5 |

### 문체 지침

**하세요:**
- 능동태 사용
- 짧은 문장 작성
- 행동부터 제시
- 일관된 용어 사용
- 예시를 충분히 포함

**하지 마세요:**
- 설명 없는 전문 용어 사용
- 사전 지식 가정
- 긴 텍스트 벽 작성
- 모호한 표현 사용
- 시제 혼용

**예시 변환:**

나쁨: "요청 본문은 아래에 문서화된 다양한 매개변수를 포함하는 JSON 객체로 채울 수 있습니다."

좋음: "다음 매개변수가 포함된 JSON 객체를 보내세요:"

### 안티패턴

- **나중에 쓰는 문서** — API가 "완료"된 뒤에 문서 작성
- **레퍼런스만 있음** — 튜토리얼이나 가이드 없음
- **낡은 예시** — 작동하지 않는 코드
- **버전 관리 없음** — 모든 API 버전에 같은 문서 사용
- **PDF 문서** — 검색 불가, 유지관리 어려움
- **내부 전문 용어** — 개발자가 모르는 용어 사용
- **오류 문서 누락** — 오류 코드 설명 없음
- **피드백 루프 없음** — 문서 문제를 신고할 수 없음

---

title: 개발자 온보딩 impact: CRITICAL tags: dx, onboarding, activation, time-to-value

개발자 온보딩

영향도: 매우 높음

첫 API 호출까지 걸리는 시간은 가장 중요한 활성화 지표입니다. 마찰이 1분 늘어날 때마다 개발자를 잃습니다.

개발자 온보딩 퍼널

가입                            100% ────────────────────────
    │
    ▼ (마찰: 양식, 이메일 확인)
API 키 받기                       70% ─────────────────
    │
    ▼ (마찰: 복잡성, 혼란)
첫 API 호출                       40% ───────────
    │
    ▼ (마찰: 설정, 환경)
사용 사례 완료                    20% ─────
    │
    ▼ (마찰: 엣지 케이스, 지원)
활성 개발자                       10% ──

목표: 각 단계의 전환율을 최대화하세요.

첫 호출까지 걸리는 시간 벤치마크

온보딩 흐름 설계

좋은 온보딩 흐름:

1. 가입(30초)
   - OAuth/SSO 옵션
   - 최소 필드(이메일 + 비밀번호)
   - 샌드박스에는 이메일 확인 없음

2. API 키(1분)
   - 가입 시 자동 생성
   - 대시보드에서 즉시 표시
   - 피드백이 있는 복사 버튼

3. 빠른 시작(5분)
   - 언어 선택기
   - 복사해 붙여넣는 코드 샘플
   - 테스트 엔드포인트(샌드박스)

4. 첫 성공(10분)
   - 안내형 튜토리얼
   - 실제 사용 사례 완료
   - 명확한 다음 단계

나쁜 온보딩 흐름:

1. 긴 가입 양식(5개 이상 필드)
2. 이메일 확인 필수
3. 회사 승인/대기 목록
4. 건너뛸 수 없는 대시보드 투어
5. 설정에 숨겨진 API 키
6. 코드 샘플 없음
7. 문서만 있음(빠른 시작 없음)

빠른 시작 페이지 구성

필수 요소:

# 빠른 시작

## 1. SDK 설치

[언어 탭: curl | Python | Node | Ruby | Go | Java]

```bash
pip install example-sdk

2. API 키 받기

내 API 키: sk_test_4eC39Hq... [복사]

3. 첫 요청 만들기

import example

client = example.Client("sk_test_4eC39HqL...")
result = client.users.create(email="[email protected]")
print(result.id)  # usr_123abc

4. 작동 확인

[대시보드 →]에서 방금 생성한 사용자를 확인하세요.

다음 단계

• [전체 가이드 →]
• [API 레퍼런스 →]
• [코드 예시 →]

### 인터랙티브 샌드박스 요구 사항

| 기능 | 우선순위 | 영향 |
|---------|----------|--------|
| **가입 불필요** | 매우 높음 | 가장 큰 마찰 제거 |
| **미리 채운 예시** | 매우 높음 | 즉시 시작 |
| **실제 API 응답** | 높음 | 신뢰 형성 |
| **여러 언어** | 높음 | 모든 개발자 지원 |
| **코드 저장/공유** | 중간 | 팀 협업 |
| **오류 설명** | 중간 | 셀프서비스 디버깅 |

### 온보딩 체크리스트 패턴

**대시보드 진행 표시:**

시작하기 4개 중 2개 완료 ─────────────────────────────────────────────────

[✓] 계정 생성 [✓] API 키 받기 [ ] 첫 API 호출 만들기 [시작 →] [ ] 웹훅 설정 [자세히 보기 →]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

### 첫 실행 경험 모범 사례

**하세요:**
- 가입 직후 API 키 표시
- 키와 코드에 원클릭 복사 제공
- 기본값을 테스트/샌드박스 모드로 설정
- 인라인 코드 검증 포함
- 성공 확인 표시
- 논리적인 다음 단계 제안

**하지 마세요:**
- 체험판에 결제 정보 요구
- 중첩 메뉴에 API 키 숨김
- 대시보드 투어 강제
- 프로덕션 모드에서 시작
- 개발자가 "작동한 건가?"라고 의심하게 둠

### 언어 우선순위

**도입률 기준으로 SDK/문서 우선순위 지정:**

| 우선순위 | 언어 | 이유 |
|----------|-----------|-----------|
| **1구간** | Python, JavaScript/Node, curl | 가장 높은 도입률 |
| **2구간** | Go, Ruby, Java | 특정 산업/환경에서 강함 |
| **3구간** | PHP, C#/.NET | 엔터프라이즈/레거시 |
| **4구간** | Swift, Kotlin | 모바일 특화 |

### 온보딩 성공 측정

**핵심 지표:**

| 지표 | 공식 | 목표 |
|--------|---------|--------|
| **API 키까지 걸리는 시간** | 가입 → 키 생성 | < 2분 |
| **첫 호출까지 걸리는 시간** | 가입 → 첫 API 요청 | < 15분 |
| **활성화율** | 첫 호출 / 가입 | > 50% |
| **1일차 유지율** | 2일차 활성 / 가입 | > 30% |
| **가치 도달 시간** | 가입 → 사용 사례 완료 | < 1시간 |

### 온보딩 오류 처리

**좋은 오류 경험:**

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "제공된 API 키가 유효하지 않습니다",
    "suggestion": "게시 가능 키가 아니라 대시보드의 API 키를 사용하고 있는지 확인하세요",
    "doc_url": "https://docs.example.com/authentication"
  }
}

인라인 제안:

오류: 401 Unauthorized

API 키가 올바르지 않은 것 같습니다. 다음 순서로 고치세요:

1. 대시보드 → API 키로 이동
2. 시크릿 키(sk_로 시작)를 복사
3. 샌드박스에는 테스트 키를 쓰고 있는지 확인

[API 키 받기 →]

안티패턴

• 영업 장벽 — API 접근 전에 데모/통화 요구
• 키 보물찾기 — API 키가 설정 깊숙이 묻혀 있음
• 문서뿐인 빠른 시작 — 인터랙티브 요소 없음
• 프로덕션 우선 — 개발자를 프로덕션 모드에서 시작시킴
• curl 예시 없음 — 간단한 테스트에도 SDK를 강제
• 획일적 온보딩 — 모든 사용 사례에 같은 온보딩 제공
• 방치된 온보딩 — 막힌 개발자에게 후속 조치 없음
• 성공 침묵 — 작동했을 때 확인이 없음

---

title: 개발자 친화적 오류 처리 impact: HIGH tags: dx, errors, debugging, developer-experience

개발자 친화적 오류 처리

영향도: 높음

오류는 피할 수 없습니다. 훌륭한 오류 처리는 좌절을 빠른 수정으로 바꿉니다. 나쁜 오류 처리는 개발자를 경쟁사로 보냅니다.

오류 응답 구성

완전한 오류 응답:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "금액은 센트 단위의 양의 정수여야 합니다",
    "param": "amount",
    "doc_url": "https://docs.example.com/api/errors#parameter_invalid",
    "request_id": "req_7d82fcb9e3a4"
  }
}

필수 오류 필드:

HTTP 상태 코드 사용

오류 타입 범주

error.type
├── api_error                 # 서버 측 이슈
│   ├── internal_error
│   ├── service_unavailable
│   └── upstream_error
│
├── authentication_error      # 인증 이슈
│   ├── invalid_api_key
│   ├── expired_token
│   └── missing_auth
│
├── authorization_error       # 권한 이슈
│   ├── insufficient_permissions
│   └── restricted_resource
│
├── invalid_request_error     # 클라이언트 실수
│   ├── parameter_missing
│   ├── parameter_invalid
│   └── parameter_unknown
│
├── rate_limit_error          # 속도 제한
│   └── too_many_requests
│
└── resource_error            # 리소스 이슈
    ├── resource_not_found
    ├── resource_already_exists
    └── resource_locked

검증 오류 세부 정보

좋은 검증 오류(여러 필드):

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "요청에 유효하지 않은 매개변수가 포함되어 있습니다",
    "details": [
      {
        "field": "email",
        "code": "invalid_format",
        "message": "이메일은 유효한 이메일 주소 형식이어야 합니다"
      },
      {
        "field": "amount",
        "code": "out_of_range",
        "message": "금액은 100에서 10000000 사이여야 합니다(센트 단위)"
      },
      {
        "field": "metadata.key",
        "code": "invalid_characters",
        "message": "메타데이터 키에는 문자, 숫자, 밑줄만 포함할 수 있습니다"
      }
    ],
    "request_id": "req_abc123"
  }
}

오류 메시지 작성 가이드

좋은 오류 메시지:

메시지 구성 요소:

1. 무슨 일이 일어났는가 — 문제의 명확한 설명
2. 왜 일어났는가 — 도움이 되는 경우 맥락
3. 어떻게 고치는가 — 실행 가능한 다음 단계

멱등적 오류 처리

같은 요청은 같은 오류를 반환해야 합니다:

요청 1:
POST /v1/charges
{ "amount": -100 }

응답 1:
HTTP 422
{ "error": { "code": "invalid_amount", "message": "금액은 양수여야 합니다" } }

요청 2(동일):
POST /v1/charges
{ "amount": -100 }

응답 2(동일):
HTTP 422
{ "error": { "code": "invalid_amount", "message": "금액은 양수여야 합니다" } }

Retry-After 헤더

속도 제한과 임시 오류용:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_requests",
    "message": "속도 제한을 초과했습니다. 60초 후 다시 시도하세요.",
    "retry_after": 60
  }
}

유지보수용:

HTTP/1.1 503 Service Unavailable
Retry-After: 300

{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "API가 유지보수 중입니다. 2024-01-15T10:00:00Z에 복구될 예정입니다",
    "maintenance_expected_end": "2024-01-15T10:00:00Z"
  }
}

SDK 오류 처리

좋은 SDK 오류 설계:

from example import Client
from example.errors import (
    AuthenticationError,
    RateLimitError,
    ValidationError,
    APIError
)

client = Client("sk_test_...")

try:
    charge = client.charges.create(amount=1000)
except AuthenticationError as e:
    # API 키 이슈
    print(f"API 키를 확인하세요: {e.message}")
except RateLimitError as e:
    # 기다렸다가 재시도
    time.sleep(e.retry_after)
    retry()
except ValidationError as e:
    # 요청 수정
    for detail in e.details:
        print(f"{detail.field}: {detail.message}")
except APIError as e:
    # 서버 오류 - 로그 및 알림
    print(f"API 오류: {e.message}")
    print(f"요청 ID: {e.request_id}")
    alert_team(e)

디버깅용 오류 로깅

오류 로그에 포함할 항목:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "request_id": "req_abc123",
  "error_code": "validation_failed",
  "path": "/v1/charges",
  "method": "POST",
  "client_ip": "203.0.113.50",
  "api_version": "2024-01-01",
  "params_sanitized": {
    "amount": 1000,
    "currency": "usd"
  },
  "error_details": [...],
  "stack_trace": "..." // 내부 전용
}

지원 중단 경고

지원 중단 기능에는 경고 포함:

{
  "data": { ... },
  "warnings": [
    {
      "code": "deprecated_parameter",
      "message": "'source' 매개변수는 지원 중단 예정입니다. 대신 'payment_method'를 사용하세요.",
      "deprecated_at": "2024-01-01",
      "removal_date": "2024-07-01",
      "doc_url": "https://docs.example.com/migration/payment-methods"
    }
  ]
}

오류 문서화

모든 오류 코드를 문서화:

# API 오류 레퍼런스

## authentication_error

### invalid_api_key
API 키가 유효하지 않거나 폐기되었습니다.

**원인:**
- API 키 오타
- 프로덕션에서 테스트 키 사용(또는 반대)
- 키가 삭제됨

**해결 방법:**
1. 대시보드 → API 키에서 키 확인
2. 올바른 환경의 키를 사용 중인지 확인
3. 필요한 경우 새 키 생성

**예시:**
```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "제공된 API 키가 유효하지 않습니다"
  }
}

### 안티패턴

- **일반 오류** — "문제가 발생했습니다"는 개발자에게 아무것도 알려주지 않음
- **요청 ID 누락** — 지원 과정에서 오류를 추적할 수 없음
- **잘못된 상태 코드** — 오류에 200, 검증 실패에 500 사용
- **오류 코드 없음** — 사람이 읽는 메시지만 있고 프로그램으로 처리 불가
- **내부 정보 노출** — 프로덕션에서 스택 추적, 데이터베이스 오류 노출
- **일관되지 않은 형식** — 엔드포인트마다 오류 형태가 다름
- **재시도 안내 없음** — Retry-After 없는 속도 제한
- **문서화되지 않은 오류** — 오류 코드가 문서에 없음
- **정보 누출** — "사용자 없음"과 "유효하지 않은 인증 정보"를 구분 노출
- **조용한 실패** — 오류여야 할 상황에서 성공 처리

---

title: 통합 마켓플레이스 전략 impact: MEDIUM tags: marketplace, integrations, partners, ecosystem

통합 마켓플레이스 전략

영향도: 중간

통합 마켓플레이스는 플랫폼 가치를 증폭합니다. 통합 하나하나가 플랫폼을 더 끈끈하고 가치 있게 만듭니다.

마켓플레이스 성숙 단계

통합 유형

통합 우선순위 프레임워크

각 통합에 점수 부여(1-5):

통합 우선순위 매트릭스:

                       높은 수요
                         │
           ┌─────────────┼─────────────┐
           │  파트너     │   지금      │
           │  우선       │   구축      │
           │             │             │
낮은 노력 ─┼─────────────┼─────────────┼─ 높은 노력
           │             │             │
           │ 우선순위    │   파트너    │
           │ 낮춤        │   전용      │
           └─────────────┼─────────────┘
                         │
                       낮은 수요

파트너 포털 요구 사항

셀프서비스 파트너 프로그램에 필요한 것:

통합 목록 페이지 구성

좋은 마켓플레이스 목록:

# Slack 통합

Example 계정을 Slack에 연결해 실시간 알림을 받으세요.

## 기능
- 주문이 생성되면 알림 받기
- 결제 실패 알림 받기
- 채널로 일일 요약 리포트 받기

## 설정(2분)
1. "Slack 연결" 클릭
2. 워크스페이스 선택
3. 알림 채널 선택
4. 알림 선호 설정 구성

## 가격
모든 요금제에서 무료

## 요구 사항
- Slack 워크스페이스 관리자 접근
- Example 계정(모든 요금제)

[통합 설치]

---

## 리뷰(234개 리뷰 기준 4.8 ★)

"매주 우리 팀의 시간을 몇 시간씩 아껴줍니다..." - 지현, 예시 회사

## 지원
Example 제작 • [email protected]

수익 공유 모델

수익 공유 단계 예시:

통합 품질 기준

인증 요구 사항:

파트너 성공 지표

통합 시장 진출

출시 체크리스트:

□ 프로덕션에서 통합 작동
□ 목록 페이지 완료
□ 문서 게시
□ 지원팀 브리핑 완료
□ 블로그 글 초안 작성
□ 기존 사용자에게 이메일
□ 소셜 미디어 게시물 예약
□ 파트너 공동 마케팅 정렬
□ 영업팀 지원 자료 준비
□ 성공 지표 정의

마켓플레이스 범주

통합 구성 기준:

웹훅 마켓플레이스 패턴

이벤트 기반 통합용:

우리 플랫폼 → 웹훅 이벤트 → 파트너 앱

사용 가능한 이벤트:
- order.created
- order.updated
- customer.created
- payment.completed
- subscription.cancelled

파트너가 엔드포인트 등록:
POST https://partner.com/webhook
Headers: X-Signature: sha256=...
Body: { event, data, timestamp }

직접 구축 vs 파트너 vs 구매

의사결정 프레임워크:

• 직접 구축: 가치 제안의 핵심이고, 전략적이며, 품질 기준이 높을 때
• 파트너: 핵심이 아니고, 파트너 전문성이 있으며, 속도가 중요할 때
• 구매: 중요한 공백이고, 강한 파트너가 있으며, 감당 가능한 비용일 때

안티패턴

• 허영 통합 — 사용자가 아니라 로고를 위해 구축
• 품질 기준 없음 — 망가진 통합 승인
• 좀비 마켓플레이스 — 아무도 쓰지 않는 통합
• 파트너 방치 — 통합 구축자를 지원하지 않음
• 수익 집착 — 높은 수취율로 생태계를 죽임
• 인증 연극 — 실제 리뷰 없는 배지
• 범주 난립 — 너무 많은 범주로 탐색이 어려움
• 제거 프로세스 없음 — 나쁜 통합을 종료할 수 없음
• 경쟁사 회피 — 경쟁 제품과 통합하지 않음

---

title: 플랫폼 지표 및 상태 impact: CRITICAL tags: metrics, analytics, health, monitoring, kpis

플랫폼 지표 및 상태

영향도: 매우 높음

무엇을 측정하느냐가 무엇을 개선할지 결정합니다. 플랫폼 상태 지표는 기술적 신뢰성, 개발자 경험, 비즈니스 성과를 모두 포괄합니다.

플랫폼 지표 계층

┌─────────────────────────────────────────────────────────────┐
│                    비즈니스 지표                            │
│    매출 • 순달러 유지율(NDR) • 고객 수 • 확장 매출          │
├─────────────────────────────────────────────────────────────┤
│                    개발자 지표                              │
│    월간 활성 개발자(MAD) • API 호출 • 유지율 • 사용 사례 완료│
├─────────────────────────────────────────────────────────────┤
│                    경험 지표                                │
│    첫 호출까지 걸리는 시간(TTFC) • 활성화 • 지원 티켓 • CSAT│
├─────────────────────────────────────────────────────────────┤
│                    플랫폼 지표                              │
│    가동 시간 • 지연 시간 • 오류율 • 처리량                  │
└─────────────────────────────────────────────────────────────┘

핵심 플랫폼 상태 지표

개발자 경험 지표

플랫폼 비즈니스 지표

개발자 퍼널 지표

단계                지표                      목표
─────────────────────────────────────────────────────
인지                사이트 방문                성장
                    문서 방문                  성장
    │
    ▼
가입                가입                       성장
                    가입 전환율                > 5%
    │
    ▼
활성화              API 키 생성                가입의 > 80%
                    첫 API 호출                가입의 > 50%
    │
    ▼
참여                주간 활성                  활성화 사용자의 > 30%
                    개발자당 API 호출          증가
    │
    ▼
확장                업그레이드율               > 10%
                    API 사용량 월간 성장       > 20%
    │
    ▼
옹호                추천                       증가
                    커뮤니티 기여              증가

SLA 정의

표준 SLA 구간:

SLA 계산:

월간 가동 시간 = (전체 분 - 다운타임 분) / 전체 분

한 달(30일)은 43,200분

99.9% = 최대 43분 다운타임
99.95% = 최대 22분 다운타임
99.99% = 최대 4분 다운타임

오류율 분석

범주별 오류 추적:

오류 예산:

오류 예산 = 1 - SLA

99.9% SLA의 경우:
오류 예산 = 요청의 0.1%가 실패 가능
또는 월 약 43분 다운타임

API 사용량 대시보드

필수 대시보드 뷰:

개발자 코호트 분석

시간에 따른 개발자 코호트 추적:

         0주차    1주차    2주차    4주차    8주차
2024년 1월 100%    45%      32%      25%      20%
2024년 2월 100%    52%      38%      30%      24%
2024년 3월 100%    58%      45%      35%      28%
                   ↑
          주차별 개선은 온보딩 변경이
          효과를 내고 있음을 보여줌

속도 제한 지표

개발자 만족도 지표

알림 전략

알림 우선순위 수준:

지표 리뷰 주기

안티패턴

• 허영 지표 — 활성 사용자가 아니라 전체 사용자 추적
• 세분화 없음 — 모든 개발자 유형에 같은 지표 사용
• 후행 지표만 있음 — 선행 지표 없음
• 알림 피로 — 실행 불가능한 알림이 너무 많음
• 벤치마크 없음 — 목표 없는 지표
• 지표 사일로 — 플랫폼 지표와 비즈니스 지표가 분리됨
• 지표 게임화 — 결과가 아니라 지표 자체를 최적화
• 보이지 않는 실패 — 조용한 오류를 추적하지 않음
• 코호트 누락 — 집계만 있고 시간 기반 분석 없음

---

title: SDK 및 라이브러리 전략 impact: HIGH tags: sdk, libraries, developer-tools, client-libraries

SDK 및 라이브러리 전략

영향도: 높음

대부분의 개발자는 SDK를 통해 API를 경험합니다. SDK는 각 언어 생태계에 자연스럽게 느껴져야 합니다.

SDK 가치 제안

SDK를 만드는 이유:

언어 우선순위 프레임워크

1구간 - 필수(먼저 구축):

2구간 - 성장(두 번째 구축):

3구간 - 확장(수요 기반):

SDK 생성 전략

권장 접근:

• 1구간: 최고의 개발자 경험을 위해 수기 작성
• 2구간: 생성 후 수기 개선
• 3구간: OpenAPI 명세에서 생성

SDK 설계 원칙

1. 언어 관습을 따르기:

# Python: snake_case, 컨텍스트 매니저
with client.batch() as batch:
    batch.create_user(email="[email protected]")
    batch.create_order(user_id="usr_123")

// JavaScript: camelCase, promise/async
const user = await client.users.create({
  email: '[email protected]'
});

// Go: 내보낸 타입, 명시적 오류
user, err := client.Users.Create(ctx, &CreateUserParams{
    Email: "[email protected]",
})

2. 일관된 리소스 접근 패턴:

# 리소스 기반 접근
client.users.create(...)
client.users.retrieve("usr_123")
client.users.update("usr_123", ...)
client.users.delete("usr_123")
client.users.list(limit=10)

# 중첩 리소스
client.users.orders.list("usr_123")

3. 가능한 곳에서는 타입 안전성 제공:

// TypeScript: 전체 타입 정의
interface CreateUserParams {
  email: string;
  name?: string;
  metadata?: Record<string, string>;
}

interface User {
  id: string;
  email: string;
  name: string | null;
  created_at: string;
}

const user: User = await client.users.create({
  email: '[email protected]'
});

SDK 기능 체크리스트

오류 처리 패턴

좋은 SDK 오류 설계:

from example import Client, APIError, AuthenticationError, RateLimitError

client = Client("sk_test_...")

try:
    user = client.users.create(email="invalid")
except AuthenticationError as e:
    # 유효하지 않은 API 키
    print(f"인증 실패: {e.message}")
except RateLimitError as e:
    # 속도 제한 - 지연 후 재시도
    print(f"속도 제한. {e.retry_after}초 후 다시 시도")
except APIError as e:
    # 일반 API 오류
    print(f"API 오류: {e.code} - {e.message}")
    print(f"요청 ID: {e.request_id}")

오류 클래스 계층:

ExampleError (기본)
├── APIError
│   ├── AuthenticationError
│   ├── AuthorizationError
│   ├── NotFoundError
│   ├── ValidationError
│   └── RateLimitError
├── NetworkError
│   ├── TimeoutError
│   └── ConnectionError
└── SDKError
    └── ConfigurationError

페이지네이션 패턴

좋은 페이지네이션(자동 페이지네이션):

# 수동 페이지 처리 없이 모든 사용자 반복
for user in client.users.list(limit=100):
    process(user)

# 또는 비동기로
async for user in client.users.list():
    await process(user)

수동 페이지네이션 접근:

page = client.users.list(limit=10)
print(page.data)           # 사용자 목록
print(page.has_more)       # 불리언
print(page.next_page())    # 다음 페이지 가져오기

SDK 문서 요구 사항

언어별 문서에 포함할 것:

1. 설치 지침
2. 인증 설정
3. 기본 사용 예시
4. 오류 처리
5. 고급 설정
6. 마이그레이션 가이드(버전 업그레이드)

예시 구조:

# Python SDK

## 설치
pip install example-sdk

## 빠른 시작
```python
from example import Client
client = Client("sk_test_...")

인증

[API 키, OAuth 등에 대한 세부 정보]

리소스

• Users
• Orders

오류 처리

[예외 타입과 처리]

설정

[타임아웃, 재시도, 로깅]

### SDK 버전 관리 전략

| API 변경 | SDK 변경 | Semver |
|------------|------------|--------|
| 새 엔드포인트 | 새 메서드 | Minor (1.x.0) |
| 새 선택 매개변수 | 새 선택 매개변수 | Minor (1.x.0) |
| 새 필수 매개변수 | 호환성 깨는 변경 | Major (x.0.0) |
| 엔드포인트 제거 | 메서드 제거 | Major (x.0.0) |
| 버그 수정 | 버그 수정 | Patch (1.0.x) |

**버전 지원 정책:**

현재 메이저 버전: 전체 지원 이전 메이저 버전: 보안 수정만(12개월) 더 오래된 버전: 미지원

### SDK 테스트 전략

| 테스트 유형 | 목적 | 커버리지 |
|-----------|---------|----------|
| **단위 테스트** | SDK 로직 | 90%+ |
| **통합 테스트** | 실제 API 호출 | 핵심 흐름 |
| **생성 테스트** | OpenAPI 준수 | 모든 엔드포인트 |
| **예시 테스트** | 문서 정확도 | 모든 예시 |

### 안티패턴

- **얇은 래퍼** — HTTP를 감싸기만 하고 추가 가치가 없는 SDK
- **관용적이지 않은 코드** — Java처럼 느껴지는 Ruby SDK
- **타입 누락** — JS에 TypeScript 정의 없음
- **일관되지 않은 이름** — 언어마다 다른 패턴
- **오류 맥락 없음** — 세부 정보 없는 일반 오류
- **버전 고정** — 특정 API 버전에 고정된 SDK
- **거대한 SDK** — 모듈형 패키지가 아니라 모든 것을 포함
- **변경 로그 없음** — 마이그레이션 안내 없는 업데이트

---

title: API 버전 관리 및 지원 중단 예고 impact: HIGH tags: versioning, deprecation, breaking-changes, migration

API 버전 관리 및 지원 중단 예고

영향도: 높음

버전 관리와 지원 중단 예고 방식은 개발자 신뢰를 결정합니다. 예고 없는 호환성 깨는 변경은 관계를 무너뜨립니다.

버전 관리 전략 비교

권장: 메이저 버전은 URL 경로, 마이너는 날짜 기반 버전 관리

버전 수명주기 단계

┌─────────┐    ┌──────────┐    ┌────────────┐    ┌───────────┐
│  알파   │ →  │   베타   │ →  │   안정     │ →  │지원 중단  │ → 종료
│         │    │          │    │            │    │예고       │
│SLA 없음 │    │제한적    │    │전체 SLA    │    │마이그레이션│
│깨질 수 있음│ │SLA       │    │지원        │    │기간       │
└─────────┘    └──────────┘    └────────────┘    └───────────┘

호환성을 깨지 않는 변경과 깨는 변경

호환성을 깨지 않음(언제든 배포 가능):

호환성을 깨는 변경(새 버전 필요):

지원 중단 예고 일정

권장 최소 일정:

커뮤니케이션 주기:

0개월:     지원 중단 예고 발표
3개월:     리마인더 이메일
6개월:     경고 헤더 시작
9개월:     최종 리마인더
12개월:    신규 통합 차단
18개월:    최종 종료 경고
24개월:    API 종료

지원 중단 헤더 패턴

지원 중단 엔드포인트의 응답 헤더:

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jan 2025 00:00:00 GMT
Sunset: Sun, 01 Jul 2025 00:00:00 GMT
Link: <https://docs.example.com/migration>; rel="deprecation"

응답 본문의 경고:

{
  "data": { ... },
  "warnings": [
    {
      "code": "deprecated_endpoint",
      "message": "이 엔드포인트는 지원 중단 예정이며 2025-07-01에 제거됩니다",
      "doc_url": "https://docs.example.com/v2-migration"
    }
  ]
}

마이그레이션 가이드 구조

모든 호환성 깨는 변경에는 마이그레이션 가이드가 필요합니다:

# v1에서 v2로 마이그레이션

## 개요
v2는 개선된 오류 처리와 일관된 이름 규칙을 도입합니다.

## 일정
- v2 출시: 2024년 1월 1일
- v1 지원 중단 예고: 2024년 7월 1일
- v1 종료: 2025년 1월 1일

## 호환성 깨는 변경

### 1. 고객 엔드포인트 이름 변경

**이전(v1):**
```bash
GET /v1/users/{id}

이후(v2):

GET /v2/customers/{id}

마이그레이션 단계:

1. 코드의 엔드포인트 URL 업데이트
2. SDK를 v2.0으로 업데이트
3. 필드 매핑 업데이트(아래 참조)

2. 응답 형식 변경

이전(v1):

{"user_id": "123", "mail": "[email protected]"}

이후(v2):

{"id": "cus_123", "email": "[email protected]"}

SDK 업그레이드 가이드

[SDK 마이그레이션 문서 링크]

도움이 필요하신가요?

마이그레이션 지원은 [email protected]으로 문의하세요.

### 버전 공존 전략

**여러 버전 운영:**

/v1/* → v1 핸들러(유지관리 모드) /v2/* → v2 핸들러(활발한 개발)

공유: 인증, 속도 제한, 로깅 분리: 비즈니스 로직, 응답 형식

**기능 플래그 접근:**

```python
def get_user(user_id, version):
    user = db.get_user(user_id)

    if version == "v1":
        return format_v1_response(user)
    elif version == "v2":
        return format_v2_response(user)

변경 로그 모범 사례

좋은 변경 로그 항목:

## 2024-01-15

### 추가
- 환불 처리를 위한 새 `refunds` 엔드포인트
- 모든 리소스의 `metadata` 필드

### 변경
- 속도 제한이 분당 100개 요청에서 200개 요청으로 증가
- `status` 필드에 이제 `pending_review` 값 포함

### 지원 중단 예고
- `GET /v1/users` - 대신 `GET /v2/customers` 사용
  종료일: 2025-01-15
  [마이그레이션 가이드 →]

### 수정
- 페이지네이션이 중복 결과를 반환하던 문제 수정

버전 지원 매트릭스

무엇이 지원되는지 명확히 전달:

호환성 깨는 변경을 부드럽게 처리하기

추가 방식(권장):

// 기존 필드를 바꾸는 대신...
{
  "status": "completed"  // 이것은 바꾸지 마세요
}

// ...새 필드를 추가
{
  "status": "completed",
  "status_v2": {
    "code": "completed",
    "reason": "delivered"
  }
}

전환 기간의 병렬 엔드포인트:

GET /v1/users/{id}      # 이전 형식, 지원 중단 예고
GET /v2/customers/{id}  # 새 형식, 권장

안티패턴

• 조용한 호환성 파괴 — 버전 관리 없이 동작 변경
• 영구 베타 — 버전 관리 책임을 피하려고 "베타" 사용
• 너무 많은 버전 — 활성 버전이 2-3개를 넘음
• 종료일 없음 — 영원히 지원 중단 예고 상태
• 짧은 지원 중단 주기 — 12개월 미만
• 마이그레이션 경로 없음 — 업그레이드 가이드 없는 새 버전
• 날짜 기반 버전 파괴 — 릴리스 후 2024-01-15 변경
• 본문의 버전 — URL/헤더가 아니라 요청 본문에 버전 입력
• 강제 업그레이드 — 충분한 예고 없이 종료