Documentazione API
Guida alla memorizzazione nella cache delle risposte e all'integrazione CDN
Ottimizza le prestazioni di Smart Money API con strategie di caching intelligenti. Scopri le intestazioni HTTP della cache, la validazione ETag, l'integrazione CDN e i modelli di caching lato client per ridurre la latenza e i costi di banda.
Pubblicato il 21 marzo 2026
•
16 min di lettura
•
Prestazioni
Panoramica sulla cache
Gli endpoint di Smart Money API forniscono dati di mercato sulle criptovalute che cambiano con frequenze diverse. Alcuni dati (indirizzi di whale, tassi di funding) si aggiornano ogni pochi secondi, mentre altri dati (analisi storiche, contenuti educativi) rimangono statici per ore. Il caching intelligente migliora notevolmente le prestazioni e riduce i costi.
Smart Money API implementa una strategia di caching a tre livelli:
- Cache CDN Edge — Distribuzione globale dei contenuti con invalidazione automatica della cache
- Cache del browser HTTP — Caching lato client utilizzando intestazioni HTTP standard
- Cache dell'applicazione — Caching in memoria per dataset accessi frequentemente
Approfondimento sulle prestazioni: Le risposte memorizzate nella cache vengono servite 50-100 volte più velocemente rispetto alle richieste API nuove e consentono un notevole risparmio di banda. Un'integrazione correttamente memorizzata nella cache può ridurre il trasferimento dei dati del 70-85%.
Ogni risposta di Smart Money API include direttive di cache che indicano ai client e ai CDN per quanto tempo i dati rimangono validi. Comprendere queste direttive e implementarle correttamente è fondamentale per prestazioni ottimali.
Fondamenti del caching
Il caching HTTP opera in base alle intestazioni di risposta che indicano se il contenuto può essere memorizzato nella cache e per quanto tempo.
Intestazione Cache-Control
Il meccanismo principale per controllare il comportamento della cache. Ogni risposta di Smart Money API include un'intestazione Cache-Control che specifica:
- max-age — Durata in secondi per cui la risposta rimane valida
- public/private — Se le cache intermedie possono memorizzarla
- must-revalidate — Se verificare la freschezza prima di servire
- no-store — Non memorizzare dati sensibili
Esempi di intestazioni di cache
Diversi endpoint hanno requisiti di cache diversi:
// Dati sugli indirizzi delle whale (aggiornati ogni 5 minuti)
Cache-Control: public, max-age=300
ETag: "abc123def456"
// Tassi di funding in tempo reale (aggiornati ogni secondo)
Cache-Control: public, max-age=1
ETag: "xyz789abc123"
// Dati storici (non cambiano)
Cache-Control: public, max-age=86400, immutable
ETag: "static-content-v1"
Durata della cache per tipo di endpoint
| Tipo di dati |
Durata della cache |
Caso d'uso |
| Funding in tempo reale |
1-5 secondi |
Trading live, dimensionamento delle posizioni |
| Movimenti delle whale |
5 minuti |
Conferma dei segnali, avvisi |
| OHLCV giornaliero |
1 ora |
Analisi tecnica, grafici |
| Analisi storica |
24 ore |
Backtesting, ricerca |
| Contenuti statici |
7 giorni |
Documentazione API, guide, configurazione |
Ottieni la tua chiave API in 30 secondi
Pronto a costruire? Ottieni una chiave API gratuita (200 chiamate/giorno, nessuna carta) e inizia a recuperare dati live su whale, funding e on-chain.
Ottieni la tua chiave API →ETag e richieste condizionali
Gli ETag (Entity Tags) forniscono un modo efficiente per convalidare il contenuto memorizzato nella cache senza scaricare l'intero corpo della risposta.
Come funzionano gli ETag
- Richiesta iniziale — Il client richiede dati, il server risponde con ETag
- Memorizzazione nella cache — Il client memorizza la risposta con ETag
- Richiesta successiva — Il client invia l'header If-None-Match con l'ETag memorizzato
- Validazione — Se i dati non sono cambiati, il server restituisce 304 Not Modified
- Larghezza di banda risparmiata — Nessun corpo della risposta inviato, enorme risparmio di larghezza di banda
Implementazione ETag
// Prima richiesta
GET /v1/whales/btc HTTP/1.1
// La risposta include l'ETag
HTTP/1.1 200 OK
ETag: "8a3b9c2d"
Cache-Control: public, max-age=300
Content-Type: application/json
{...corpo della risposta...}
// Dopo la scadenza della cache, invia If-None-Match
GET /v1/whales/btc HTTP/1.1
If-None-Match: "8a3b9c2d"
// Se non modificato, il server risponde con 304
HTTP/1.1 304 Not Modified
ETag: "8a3b9c2d"
Cache-Control: public, max-age=300
// Nessun corpo inviato! Larghezza di banda risparmiata
Forza dell'ETag
Gli ETag possono essere forti o deboli:
| Tipo |
Formato |
Caso d'uso |
| ETag forte |
"8a3b9c2d" |
Identico byte per byte, utilizzato per la validazione |
| ETag debole |
W/"8a3b9c2d" |
Equivalente semanticamente, per cambiamenti di visualizzazione |
Direttive di controllo della cache
Comprendere le direttive Cache-Control consente di costruire strategie di caching ottimali per la tua applicazione.
Riferimento delle direttive
| Direttiva |
Significato |
Esempio |
| max-age |
Secondi in cui la risposta rimane fresca |
max-age=300 |
| public |
La cache può memorizzare e condividere |
public |
| private |
Cache solo per il destinatario |
private |
| must-revalidate |
Rivalida quando obsoleto |
must-revalidate |
| no-cache |
Deve rivalidare prima dell'uso |
no-cache |
| no-store |
Non memorizzare affatto |
no-store |
| immutable |
Non cambia mai, cache per sempre |
immutable |
| s-maxage |
Durata della cache CDN |
s-maxage=3600 |
Modelli pratici di Cache-Control
// Modello 1: Cache del browser, CDN per 1 ora
Cache-Control: public, max-age=300, s-maxage=3600
// Modello 2: Dati per utente, nessuna cache proxy
Cache-Control: private, max-age=1800
// Modello 3: Sempre fresco, sempre verifica
Cache-Control: public, no-cache, must-revalidate
// Modello 4: Asset versionato immutabile
Cache-Control: public, max-age=31536000, immutable
Integrazione CDN
Smart Money API consegna le risposte attraverso la rete CDN globale di Cloudflare, memorizzando automaticamente le risposte in sedi periferiche in tutto il mondo per una latenza minima.
Come funziona Smart Money CDN
- Richiesta dell'utente — La richiesta raggiunge la sede periferica Cloudflare più vicina
- Controllo della cache — La sede periferica verifica se la risposta è memorizzata nella cache e fresca
- Cache Hit — Se memorizzato nella cache, serve immediatamente con una latenza <10ms
- Cache Miss — Se non memorizzato nella cache, recupera dal server di origine
- Memorizza e serve — Memorizza la risposta nella cache e la consegna all'utente
Configurazione della chiave di cache
Cloudflare utilizza chiavi di cache per identificare in modo univoco le risposte memorizzate nella cache. Per impostazione predefinita:
- Il percorso della richiesta e i parametri di query sono inclusi
- La maggior parte degli header viene ignorata (per massimizzare i cache hit)
- Gli header di autorizzazione NON sono inclusi (nessuna perdita di account)
- Gli header personalizzati possono essere inclusi tramite l'header Vary
Pulizia della cache CDN
Smart Money purga automaticamente la cache CDN quando i dati vengono aggiornati:
// Pulisci un URL specifico dalla CDN
curl -X POST "https://api.smartmoneyapi.com/v1/cache/purge" \
-H "Authorization: Bearer token" \
-d '{
"urls": [
"https://api.smartmoneyapi.com/v1/whales/btc"
]
}'
Misurazione delle prestazioni CDN
Controlla gli header della risposta per vedere se la richiesta è stata servita dalla cache:
// Cache hit dalla sede periferica CDN
CF-Cache-Status: HIT
CF-RAY: 8a9b7c6d5e4f3g2h
Age: 45 // secondi dalla memorizzazione nella cache
// Cache miss, recuperato dal server di origine
CF-Cache-Status: MISS
Age: 0
Caching lato client
Implementa il caching nella tua applicazione per ridurre ulteriormente le chiamate API e migliorare la reattività.
Implementazione della cache del browser
// Crea lo storage della cache
const cache = new Map();
async function fetchWithCache(url) {
// Controlla prima la cache
const cached = cache.get(url);
if (cached && !isCacheExpired(cached)) {
return cached.data;
}
// Recupera dall'API
const response = await fetch(url);
const data = await response.json();
// Analizza la durata della cache dagli header
const cacheControl = response.headers
.get('cache-control');
const maxAge = parseMaxAge(cacheControl);
// Memorizza nella cache
cache.set(url, {
data,
expiry: Date.now() + (maxAge * 1000)
});
return data;
}
Service Worker Caching
Per supporto offline e strategie di caching avanzate, utilizza i Service Worker:
// Memorizza le risposte dell'API con il Service Worker
self.addEventListener('fetch', (event) => {
if (event.request.url.includes('api.smartmoneyapi.com')) {
// Prima la rete, poi la cache come fallback
event.respondWith(
fetch(event.request)
.then(response => {
// Aggiorna la cache con la risposta fresca
caches.open('api-cache')
.then(cache => cache.put(
event.request, response.clone()));
return response;
})
.catch(() =>
caches.match(event.request))
);
}
});
Strategie di Cache Busting
A volte è necessario forzare i client a ottenere dati freschi. Utilizza queste tecniche:
Parametro di Versione
Aggiungi un parametro di versione per invalidare le cache quando i dati cambiano:
// Includi la versione dei dati o un timestamp
https://api.smartmoneyapi.com/v1/whales/btc?v=1709980800
// Quando i dati vengono aggiornati, incrementa la versione
https://api.smartmoneyapi.com/v1/whales/btc?v=1709981000
// Nuovo URL = nuova voce nella cache
Forza la Rivalidazione
Sovrascrivi la cache con Cache-Control: no-cache quando hai bisogno di dati freschi:
// JavaScript: Forza una richiesta fresca
fetch(url, {
cache: 'no-cache', // Rivalida sempre
headers: {
'Cache-Control': 'max-age=0'
}
});
Monitoraggio delle Prestazioni della Cache
Monitora i tassi di hit della cache e i miglioramenti delle prestazioni per validare la tua strategia di caching.
Metriche della Cache da Monitorare
- Tasso di Hit — Percentuale di richieste servite dalla cache (obiettivo: >70%)
- Tempo di Risposta — Latenza media (cache: <50ms, non in cache: 100-300ms)
- Larghezza di Banda Risparmiata — Riduzione del trasferimento dati
- Carico dell'Origine — Riduzione delle richieste al server di origine
Analisi degli Header della Cache
// Analizza gli header della cache della risposta
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')
};
}
Migliori Pratiche per il Caching
1. Rispetta gli Header di Risposta
Rispetta sempre gli header Cache-Control da Smart Money API. Non memorizzare nella cache contenuti contrassegnati come no-store o no-cache.
2. Implementa Richieste Condizionali
Invia gli header If-None-Match (ETag) e If-Modified-Since quando rivalidi il contenuto in cache. Risparmia larghezza di banda con risposte 304.
3. Memorizza nella Cache in Modo Appropriato per Tipo di Dati
- Dati in tempo reale (tassi di funding): cache massima di 1-5 secondi
- Segnali live (movimenti delle balene): cache di 5-30 secondi
- Dati orari (OHLCV): cache di 1 ora
- Dati storici: cache di 24 ore
- Contenuti statici: cache di 7 giorni
4. Monitora l'Efficacia della Cache
Monitora i tassi di hit e i miglioramenti della latenza. Regola i TTL in base ai requisiti di freschezza dei dati e alle prestazioni della cache.
5. Usa gli Header Vary con Cautela
Gli header Vary riducono gli hit della cache creando voci di cache separate. Usali solo quando necessario per diversi livelli di autenticazione o parametri.
6. Memorizza nella Cache a Livelli Multipli
Implementa la cache a livello di CDN, browser e applicazione. Ogni livello intercetta le richieste prima che raggiungano l'origine.
Ottimizza le Prestazioni della tua API
L'infrastruttura di caching di Smart Money API garantisce risposte inferiori a 100ms su scala globale. Implementa strategie di caching intelligenti per massimizzare le prestazioni e minimizzare i costi.
Confronta i Piani
Tutti i piani includono la cache CDN completa. I livelli superiori offrono il controllo della cache e le API di purging.