Buone pratiche
Pattern consigliati per costruire integrazioni robuste ed efficienti con le API STEF.
Rate Limiting
Rispetta gli header di rate limiting restituiti dall'API:
| Header | Descrizione |
|---|---|
X-RateLimit-Limit | Numero massimo di richieste per finestra |
X-RateLimit-Remaining | Richieste rimanenti nella finestra corrente |
X-RateLimit-Reset | Timestamp di ripristino della finestra |
Retry-After | Secondi da attendere (in caso di 429) |
Sicurezza
Archiviazione dei segreti
Utilizza le variabili d'ambiente o un gestore di segreti:
# .env
STEF_CLIENT_ID=your_client_id
STEF_CLIENT_SECRET=your_client_secret
# .gitignore
.env
Performance
Caching
- Metti in cache le risposte degli endpoint di lettura che non cambiano frequentemente
- Rispetta gli header
Cache-ControleETag - Utilizza le richieste condizionali (
If-None-Match,If-Modified-Since)
Paginazione efficiente
- Utilizza la paginazione basata su cursore fornita dall'API
- Limita il numero di elementi per pagina (
limit) allo stretto necessario - Evita di caricare tutte le pagine in una sola volta
Compressione
Abilita la compressione gzip nelle tue richieste:
curl -X GET "https://api.stef.com/v1/transport/orders" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept-Encoding: gzip"
Monitoraggio
- Registra i tempi di risposta e i codici di ritorno
- Imposta avvisi sugli errori 4xx e 5xx
- Monitora il consumo delle quote tramite il dashboard del portale