API 문서
응답 캐싱 및 CDN 통합 가이드
스마트 캐싱 전략으로 Smart Money API 성능을 최적화하세요. HTTP 캐시 헤더, ETag 검증, CDN 통합 및 클라이언트 측 캐싱 패턴을 배워 지연 시간과 대역폭 비용을 줄이세요.
2026년 3월 21일 발행
•
16분 읽기
•
성능
캐싱 개요
Smart Money API 엔드포인트는 다양한 빈도로 변경되는 암호화폐 시장 데이터를 제공합니다. 일부 데이터(고래 주소, 펀딩 비율)는 몇 초마다 업데이트되지만, 다른 데이터(역사적 분석, 교육 콘텐츠)는 몇 시간 동안 정적 상태를 유지합니다. 스마트 캐싱은 성능을 크게 향상시키고 비용을 절감합니다.
Smart Money API는 세 단계 캐싱 전략을 구현합니다:
- CDN 에지 캐시 — 자동 캐시 무효화를 통한 글로벌 콘텐츠 전달
- HTTP 브라우저 캐시 — 표준 HTTP 헤더를 사용한 클라이언트 측 캐싱
- 애플리케이션 캐시 — 자주 액세스하는 데이터셋을 위한 메모리 내 캐싱
성능 인사이트: 캐시된 응답은 새로운 API 요청보다 50-100배 빠르게 제공되며 대역폭을 크게 절약합니다. 적절히 캐시된 통합은 데이터 전송을 70-85% 줄일 수 있습니다.
모든 Smart Money API 응답에는 데이터가 유효한 기간을 클라이언트와 CDN에 알려주는 캐시 지시문이 포함됩니다. 이러한 지시문을 이해하고 올바르게 구현하는 것이 최적의 성능을 위해 중요합니다.
캐싱 기본
HTTP 캐싱은 콘텐츠를 캐시할 수 있는지와 얼마나 오래 캐시할 수 있는지를 나타내는 응답 헤더를 기반으로 작동합니다.
Cache-Control 헤더
캐시 동작을 제어하는 주요 메커니즘입니다. 모든 Smart Money API 응답에는 다음을 지정하는 Cache-Control 헤더가 포함됩니다:
- max-age — 응답이 유효한 기간(초)
- public/private — 중간 캐시가 저장할 수 있는지 여부
- must-revalidate — 제공 전에 신선도를 확인할지 여부
- no-store — 민감한 데이터를 캐시하지 않음
캐시 헤더 예제
다른 엔드포인트는 다른 캐시 요구 사항이 있습니다:
// 고래 주소 데이터(5분마다 업데이트)
Cache-Control: public, max-age=300
ETag: "abc123def456"
// 실시간 펀딩 비율(1초마다 업데이트)
Cache-Control: public, max-age=1
ETag: "xyz789abc123"
// 역사적 데이터(변경되지 않음)
Cache-Control: public, max-age=86400, immutable
ETag: "static-content-v1"
엔드포인트 유형별 캐시 기간
| 데이터 유형 |
캐시 기간 |
사용 사례 |
| 실시간 펀딩 |
1-5초 |
실시간 거래, 포지션 사이징 |
| 고래 이동 |
5분 |
신호 확인, 알림 |
| 일일 OHLCV |
1시간 |
기술적 분석, 차트 |
| 역사적 분석 |
24시간 |
백테스팅, 연구 |
| 정적 콘텐츠 |
7일 |
API 문서, 가이드, 구성 |
30초 안에 API 키 받기
준비되었나요? 무료 API 키(하루 100회 호출, 카드 불필요)를 받아 실시간 고래, 펀딩 및 온체인 데이터를 가져오세요.
API 키 받기 →ETag 및 조건부 요청
ETag(엔티티 태그)는 전체 응답 본문을 다운로드하지 않고 캐시된 콘텐츠를 효율적으로 검증하는 방법을 제공합니다.
ETag 작동 방식
- 초기 요청 — 클라이언트가 데이터를 요청하고 서버가 ETag로 응답
- 캐시 저장 — 클라이언트가 ETag와 함께 응답을 캐시
- 후속 요청 — 클라이언트가 캐시된 ETag와 함께 If-None-Match 헤더를 전송
- 검증 — 데이터가 변경되지 않은 경우, 서버는 304 Not Modified를 반환
- 대역폭 절약 — 응답 본문이 전송되지 않아 대역폭이 크게 절약됨
ETag 구현
// 첫 번째 요청
GET /v1/whales/btc HTTP/1.1
// 응답에 ETag 포함
HTTP/1.1 200 OK
ETag: "8a3b9c2d"
Cache-Control: public, max-age=300
Content-Type: application/json
{...response body...}
// 캐시가 만료된 후, If-None-Match를 전송
GET /v1/whales/btc HTTP/1.1
If-None-Match: "8a3b9c2d"
// 변경되지 않은 경우, 서버는 304를 응답
HTTP/1.1 304 Not Modified
ETag: "8a3b9c2d"
Cache-Control: public, max-age=300
// 본문이 전송되지 않음! 대역폭 절약
ETag 강도
ETags는 강력하거나 약할 수 있음:
| 유형 |
형식 |
사용 사례 |
| 강력한 ETag |
"8a3b9c2d" |
바이트 단위로 동일, 검증에 사용 |
| 약한 ETag |
W/"8a3b9c2d" |
의미적으로 동등, 표시 변경용 |
캐시 제어 지시문
Cache-Control 지시문을 이해하면 애플리케이션에 최적의 캐싱 전략을 구축할 수 있습니다.
지시문 참조
| 지시문 |
의미 |
예시 |
| max-age |
응답이 신선하게 유지되는 시간(초) |
max-age=300 |
| public |
캐시가 저장하고 공유할 수 있음 |
public |
| private |
수신자 전용 캐시 |
private |
| must-revalidate |
만료된 경우 재검증 |
must-revalidate |
| no-cache |
사용 전 재검증 필요 |
no-cache |
| no-store |
전혀 캐시하지 않음 |
no-store |
| immutable |
변경되지 않음, 영구적으로 캐시 |
immutable |
| s-maxage |
CDN 캐시 지속 시간 |
s-maxage=3600 |
실용적인 Cache-Control 패턴
// 패턴 1: 브라우저 캐시, CDN 1시간
Cache-Control: public, max-age=300, s-maxage=3600
// 패턴 2: 사용자별 데이터, 프록시 캐시 없음
Cache-Control: private, max-age=1800
// 패턴 3: 항상 신선, 항상 확인
Cache-Control: public, no-cache, must-revalidate
// 패턴 4: 변경되지 않는 버전 자산
Cache-Control: public, max-age=31536000, immutable
CDN 통합
Smart Money API는 Cloudflare의 글로벌 CDN 네트워크를 통해 응답을 전달하며, 전 세계 엣지 위치에서 응답을 자동으로 캐싱하여 최소 지연 시간을 제공합니다.
Smart Money CDN 작동 방식
- 사용자 요청 — 요청이 가장 가까운 Cloudflare 엣지 위치에 도달
- 캐시 확인 — 엣지가 응답이 캐시되었고 신선한지 확인
- 캐시 히트 — 캐시된 경우, <10ms 지연 시간으로 즉시 제공
- 캐시 미스 — 캐시되지 않은 경우, 원본 서버에서 가져옴
- 저장 및 제공 — 응답을 캐시하고 사용자에게 전달
캐시 키 구성
Cloudflare는 캐시된 응답을 고유하게 식별하기 위해 캐시 키를 사용합니다. 기본적으로:
- 요청 경로와 쿼리 매개변수가 포함됨
- 대부분의 헤더는 무시됨(캐시 히트율 극대화를 위해)
- 인증 헤더는 포함되지 않음(계정 정보 누출 방지)
- Vary 헤더를 통해 사용자 정의 헤더를 포함할 수 있음
CDN 퍼지
Smart Money는 데이터가 업데이트될 때 자동으로 CDN 캐시를 퍼지합니다:
// CDN에서 특정 URL 퍼지
curl -X POST "https://api.smartmoneyapi.com/v1/cache/purge" \
-H "Authorization: Bearer token" \
-d '{
"urls": [
"https://api.smartmoneyapi.com/v1/whales/btc"
]
}'
CDN 성능 측정
응답 헤더를 확인하여 요청이 캐시에서 제공되었는지 확인:
// CDN 엣지에서 캐시 히트
CF-Cache-Status: HIT
CF-RAY: 8a9b7c6d5e4f3g2h
Age: 45 // 캐시된 이후 초
// 캐시 미스, 원본에서 가져옴
CF-Cache-Status: MISS
Age: 0
클라이언트 측 캐싱
애플리케이션에서 캐싱을 구현하여 API 호출을 더욱 줄이고 응답성을 개선하세요.
브라우저 캐시 구현
// 캐시 저장소 생성
const cache = new Map();
async function fetchWithCache(url) {
// 캐시를 먼저 확인
const cached = cache.get(url);
if (cached && !isCacheExpired(cached)) {
return cached.data;
}
// API에서 가져오기
const response = await fetch(url);
const data = await response.json();
// 헤더에서 캐시 지속 시간 파싱
const cacheControl = response.headers
get('cache-control');
const maxAge = parseMaxAge(cacheControl);
// 캐시에 저장
cache.set(url, {
data,
expiry: Date.now() + (maxAge * 1000)
});
return data;
}
서비스 워커 캐싱
오프라인 지원 및 고급 캐싱 전략을 위해 서비스 워커를 사용하세요:
// 서비스 워커로 API 응답 캐싱
self.addEventListener('fetch', (event) => {
if (event.request.url.includes('api.smartmoneyapi.com')) {
// 네트워크 우선, 캐시로 대체
event.respondWith(
fetch(event.request)
then(response => {
// 신선한 응답으로 캐시 업데이트
caches.open('api-cache')
then(cache => cache.put(
event.request, response.clone()));
return response;
})
catch(() =>
caches.match(event.request))
);
}
});
캐시 무효화 전략
때로는 클라이언트가 새로운 데이터를 가져오도록 강제해야 합니다. 다음 기법을 사용하세요:
버전 매개변수
데이터가 변경될 때 캐시를 무효화하려면 버전 매개변수를 추가하세요:
// 데이터 버전 또는 타임스탬프 포함
https://api.smartmoneyapi.com/v1/whales/btc?v=1709980800
// 데이터 업데이트 시 버전 증가
https://api.smartmoneyapi.com/v1/whales/btc?v=1709981000
// 새 URL = 새 캐시 항목
강제 재검증
신선한 데이터가 필요할 때 Cache-Control: no-cache로 캐시를 재정의하세요:
// JavaScript: 강제 신선한 요청
fetch(url, {
cache: 'no-cache', // 항상 재검증
headers: {
'Cache-Control': 'max-age=0'
}
});
캐시 성능 모니터링
캐시 적중률과 성능 향상을 추적하여 캐싱 전략을 검증하세요.
모니터링할 캐시 메트릭
- 적중률 — 캐시에서 제공된 요청의 비율 (목표: >70%)
- 응답 시간 — 평균 지연 시간 (캐시: <50ms, 비캐시: 100-300ms)
- 절약된 대역폭 — 데이터 전송 감소
- 원본 서버 부하 — 원본 서버의 요청 감소
캐시 헤더 분석
// 응답 캐시 헤더 분석
async function analyzeCache(url) {
const response = await fetch(url);
return {
cacheControl: response.headers
get('cache-control'),
etag: response.headers.get('etag'),
age: response.headers.get('age'),
cfStatus: response.headers
get('cf-cache-status'),
contentLength:
response.headers.get('content-length')
};
}
캐싱 모범 사례
1. 응답 헤더 존중
Smart Money API의 Cache-Control 헤더를 항상 존중하세요. no-store 또는 no-cache로 표시된 콘텐츠는 캐시하지 마세요.
2. 조건부 요청 구현
캐시된 콘텐츠를 재검증할 때 If-None-Match (ETag) 및 If-Modified-Since 헤더를 보내세요. 304 응답으로 대역폭을 절약하세요.
3. 데이터 유형에 따라 적절히 캐시
- 실시간 데이터 (펀딩 레이트): 최대 1-5초 캐시
- 실시간 신호 (고래 움직임): 5-30초 캐시
- 시간별 데이터 (OHLCV): 1시간 캐시
- 역사적 데이터: 24시간 캐시
- 정적 콘텐츠: 7일 캐시
4. 캐시 효과성 모니터링
적중률과 지연 시간 향상을 추적하세요. 데이터 신선도 요구 사항과 캐시 성능에 따라 TTL을 조정하세요.
5. Vary 헤더 신중 사용
Vary 헤더는 별도의 캐시 항목을 생성하여 캐시 적중률을 감소시킵니다. 다른 인증 수준이나 매개변수가 필요한 경우에만 사용하세요.
6. 여러 계층에서 캐시
CDN, 브라우저 및 애플리케이션 수준에서 캐싱을 구현하세요. 각 계층은 원본 서버에 도달하기 전에 요청을 가로챕니다.
API 성능 최적화
Smart Money API의 캐싱 인프라는 글로벌 규모에서 100ms 미만의 응답을 보장합니다. 지능적인 캐싱 전략을 구현하여 성능을 극대화하고 비용을 최소화하세요.
플랜 비교
모든 플랜에는 전체 CDN 캐싱이 포함됩니다. 상위 티어는 캐시 제어 및 퍼징 API를 제공합니다.