---
id: pattern-api-client
title: "API Client Pattern"
category: "Pattern_Web"
status: "draft"
verification_status: "applied"
canonical_id: ""
aliases: ["API client", "HTTP client", "API 클라이언트 패턴", "adapter", "SDK wrapper"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.88
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "web", "api", "http", "platform-independent"]
raw_sources: ["일반 소프트웨어 공학 지식", "AstraAI/src/features/providers/*, src/integrations/telegram/telegramClient.ts (적용 예)"]
applied_in: ["AstraAI"]
github_commit: ""
---

# [[API Client Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
API Client 패턴은 "외부 HTTP/SDK 호출을 한 모듈로 캡슐화" 해 인증·재시도·타임아웃·에러 정규화·취소를 한 곳에서 관리하고, 호출부는 깨끗한 메서드만 보게 한다.

## 🧠 핵심 개념 (Core concepts)
1. **단일 클라이언트:** baseURL/헤더/인증을 한 곳에.
2. **횡단 관심사:** 재시도·타임아웃·취소(AbortSignal)·로깅·에러 변환을 내장.
3. **응답 정규화:** 다양한 응답을 내부 표준 형태로.
4. **인증 주입:** 토큰을 getter 로(갱신 반영).
5. **에러 passthrough/translate:** 실패를 호출부가 쓸 수 있는 형태로.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 외부 API/SDK 를 여러 곳에서 호출, 인증·재시도·에러 처리가 반복될 때.
- **사용 조건:** 호출 인터페이스 정의 가능; 인증/설정 중앙화 가능.
- **장점:** 중복 제거, 일관된 에러/재시도/취소, 교체·모킹 용이, 테스트성.
- **단점:** 추상화 비용, 만능 클라이언트화 위험.
- **대안:** fetch 직접(소규모), 생성된 SDK, GraphQL 클라이언트.
- **실패 사례:** 타임아웃/취소 누락으로 멈춤; 토큰 하드코딩(갱신 안 됨); 에러 삼킴; 재시도에 backoff 없어 폭주; 응답 형식 호출부 산재.

## 💻 코드 패턴 (Code patterns)
```text
class Client {
  constructor({ getToken, baseUrl })          # 인증은 getter 주입
  async call(path, body, { signal }) {
    const s = combine(signal, timeout(ms))     # 취소+타임아웃
    res = await fetch(baseUrl+path, { headers:{Authorization:getToken()}, signal:s })
    if (!res.ok) return normalizeError(res)    # 에러 정규화/passthrough
    return parse(res)                          # 응답 정규화
  }
}
```
적용 예: AstraAI 의 provider 어댑터(공급자별 차이 흡수→공통 SSE)와 TelegramHttpClient(getToken 게터). → [[LLM 프로바이더 추상화]], [[AITRAIN 프로바이더 추상화]].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
얇은 호출이면 fetch 직접이 낫다 — 인증/재시도/에러가 반복될 때만 클라이언트 추상화가 이득.

## 🛠️ 적용 사례 (Applied in summary)
AstraAI providers + telegramClient.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[Async Concurrency Pattern]], [[Error Handling Pattern]], [[Caching Pattern]], [[Tool Calling Pattern]]
- **참조 맥락:** 작은 모델이 외부 API 통합 코드를 작성할 때 참조.

## 📚 출처 (Sources)
- [S1] 일반 API 클라이언트 지식
- [S2] AstraAI/src/features/providers/*, integrations/telegram/telegramClient.ts — 적용 예

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
