모든 것을 할 수 있는 API는, 결국 아무것도 제대로 하지 못하는 API일 수 있습니다. 훌륭한 개발자 경험(DX)은 무한한 선택지가 아니라, 좋은 제약에서 출발합니다. 이 글은 Members Only API가 선택한 의견(Opinion)과 그 배경을 기록합니다.
좋은 제약이 만드는 일관성
의견 있는 API는 일관성을 강제합니다. 리소스 명명, 오류 구조, 인증 방식, 페이징 규칙 등에서 일관성은 학습 비용을 기하급수적으로 줄입니다.
- 리소스 경로:
/v1/members,/v1/payments,/v1/subscriptions - 식별자 포맷: 접두어+난수(
mem_,pay_,sub_) - 시간: ISO 8601 UTC, 서버 생성 필수(
createdAt,updatedAt) - 오류:
{ error: { type, code, message, docs } }
보안은 선택이 아니라 기본값: Security by Design
우리는 모든 요청에 TLS를 강제하고, 서버-사이드 비밀키 사용을 기본값으로 합니다. 민감한 연산은 명시적 권한 없이는 실행되지 않습니다.
Idempotency와 안전한 재시도
결제·멤버십 도메인에서 멱등성은 필수입니다. 우리는 Idempotency-Key 헤더를 표준으로 요구합니다.
POST /v1/payments
Idempotency-Key: 9f4e2a9a-... # 클라이언트 생성 UUID
Authorization: Bearer sk_live_...
Content-Type: application/json
{ "type": "sponsorship", "amount": 50000, "currency": "KRW", "memberId": "mem_123" }
동일 키로 재시도하면 서버는 최초 결과를 안전하게 재현합니다.
에러는 문서의 일부
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": {
"type": "payment_error",
"code": "card_declined",
"message": "결제가 거절되었습니다. 다른 결제 수단을 시도하세요.",
"docs": "https://docs.membersonly.fun#payment-errors"
}
}
우리는 모든 오류에 docs 링크를 포함해 즉시 문제 해결 경로를 제공합니다.
표현력 있는 최소 규칙: Pagination, Filtering, Expansion
리스트 엔드포인트는 세 가지 규칙으로 충분합니다.
- 페이지네이션:
?limit=50&cursor=...커서 기반, 역순 정렬이 기본 - 필터:
?status=active&memberId=mem_123 - 확장:
?expand=member로 연관 리소스 인라인 반환
스키마는 계약이다: 타입 안정성과 진화
우리는 스키마 우선 전략을 채택합니다. OpenAPI/JSON Schema를 단일 진실 원천으로, SDK/문서/테스트를 생성합니다.
// payments.create payload (TypeScript)
export interface CreatePayment {
type: 'sponsorship' | 'membership_fee' | 'digital_goods';
amount: number; // KRW in won
currency: 'KRW';
memberId: string; // mem_*
message?: string;
}
호환성 파괴 변경은 금지하며, 필드 추가는 항상 선택적이어야 합니다.
의견이 있는 DX: 왜 이것이 더 빠른가
좋은 API는 생각할 거리를 줄입니다. 개발자는 비즈니스 로직에 집중하고, 인프라의 복잡성은 API가 대신 품습니다.
우리는 가이드라인과 예제를 풍부하게 제공하고, 틀린 방법을 미리 봉쇄함으로써 통합 시간을 단축합니다.
맺음말
의견 있는 API는 배타적이 아니라 친절합니다. 단순함과 보안이라는 원칙 하에, 우리는 계속해서 개발자가 더 중요한 것에 집중할 수 있도록 길을 열겠습니다.