I limiti di consumo nelle API PHP proteggono la disponibilità e i costi del servizio, ma una policy progettata male può interrompere integrazioni legittime. Per definire limiti efficaci, non basta fissare un numero di richieste al minuto: occorre identificare chi consuma, quale operazione esegue, quale risorsa è a rischio e come si comporta il traffico reale.
Una progettazione efficace combina limiti adeguati al modello di utilizzo, contatori coerenti tra le istanze e risposte che consentano ai consumatori di recuperare. Richiede inoltre di osservare gli effetti delle regole prima di renderle più restrittive, soprattutto quando più clienti condividono le credenziali o dipendono da risorse comuni.
Distingui tasso di richieste, quota e concorrenza
Questi controlli proteggono da problemi diversi e non sono intercambiabili:
- Tasso di richieste: limita quante richieste vengono accettate in un breve intervallo. Aiuta a contenere i picchi o il traffico sostenuto che satura l’applicazione.
- Quota cumulativa: limita il consumo totale in un periodo più lungo, per esempio un certo numero di operazioni al giorno o per ciclo di fatturazione. Serve a governare l’utilizzo previsto dal contratto o i carichi costosi accumulati.
- Concorrenza: limita quante operazioni sono in esecuzione contemporaneamente. È utile quando ogni operazione può occupare worker, connessioni o risorse per molto tempo.
Un cliente può rispettare il tasso di richieste e, allo stesso tempo, accumulare molte operazioni lunghe in parallelo; può anche effettuare poche richieste che consumano una quota giornaliera costosa. Definisci il controllo in base al rischio che vuoi ridurre e, se te ne servono diversi, specifica come interagiscono e quale viene applicato per primo.
Decidi quale identità e risorsa limitare
La chiave del limite deve rappresentare un’unità di consumo che abbia senso dal punto di vista operativo. A seconda del prodotto, può essere una credenziale, un utente, un’organizzazione, un’applicazione client, un endpoint o una loro combinazione. Limitare soltanto in base all’indirizzo IP può penalizzare le reti condivise e non distingue bene i consumatori autenticati; un IP può essere un segnale complementare per il traffico anonimo o per i controlli di sicurezza.
Per i clienti autenticati, è opportuno associare la policy a un’identità stabile e applicare l’isolamento tra le organizzazioni. Una credenziale condivisa da più sistemi può nascondere chi genera un picco: quando possibile, usa credenziali separate o aggiungi dimensioni che consentano di attribuire i consumi. Evita di inserire segreti non trasformati nelle chiavi dei contatori o nei log.
Non tutti gli endpoint hanno lo stesso costo. Una query semplice e un’esportazione estesa non dovrebbero necessariamente consumare lo stesso budget. Puoi assegnare pesi o policy diverse alle operazioni costose, purché il criterio sia comprensibile e coerente per i consumatori. Verifica anche i limiti del servizio: un’API può ricevere poche richieste e tuttavia saturare una dipendenza condivisa, come un database o un provider esterno.
Scegli finestre che riflettano il modello di utilizzo
Una finestra fissa è facile da spiegare, ma può consentire un picco alla fine di un intervallo seguito da un altro all’inizio del successivo. Una finestra mobile riduce questo effetto, a costo di un maggiore lavoro di archiviazione e calcolo. Un sistema a token consente picchi limitati e controlla il tasso medio; è utile quando il traffico legittimo arriva a ondate. La scelta dipende dal modello di consumo e dalla precisione necessaria.
Non confondere un picco di attività legittimo con un abuso. Carichi pianificati, sincronizzazioni all’inizio della giornata o tentativi successivi a un’interruzione possono concentrare le richieste. Se il prodotto consente i picchi, definiscine esplicitamente la dimensione e il tempo necessario al ripristino del budget. Per le operazioni lunghe, limita anche la concorrenza o applica un controllo di ammissione prima di occupare risorse scarse.
Anche i tentativi ripetuti del client sono importanti. Se una risposta temporanea provoca nuovi tentativi immediati, il limite può aggravare il picco. Consiglia un’attesa progressiva, idealmente con variazione casuale, e definisci se le operazioni ripetute con la stessa chiave di idempotenza contano come nuove richieste o come ripetizioni sicure.
Coordina i contatori quando PHP viene eseguito su più istanze
Un contatore conservato soltanto nella memoria del processo può funzionare su una singola istanza, ma perde coerenza quando il traffico viene distribuito tra più istanze. Ogni server potrebbe accettare una parte del limite e, nel complesso, superarlo. Nelle distribuzioni con più istanze, lo stato deve essere coordinato tramite un archivio condiviso o un meccanismo equivalente con adeguate operazioni atomiche.
Progetta anche il comportamento in caso di errori del sistema dei contatori. Se non è disponibile, rifiutare tutte le richieste può interrompere i clienti legittimi; accettarle tutte può esporre una dipendenza critica. La decisione dipende dal rischio dell’endpoint: può essere ragionevole comportarsi in modo diverso per una query a basso impatto rispetto a un’operazione che genera costi elevati. Documenta il criterio e segnala i casi di degrado.
Evita chiavi dei contatori troppo generiche, che mescolano organizzazioni o endpoint, e troppo frammentate, che rendono difficile controllare il consumo totale. Definisci la scadenza e la pulizia dello stato, in modo che le chiavi temporanee non si accumulino indefinitamente. Verifica che le modifiche alla configurazione non azzerino o duplichino i contatori in modo imprevisto.
Comunica il rifiuto come parte del contratto API
Quando viene raggiunto un limite, restituisci uno stato HTTP coerente con il contratto API — di norma 429 Too Many Requests per una limitazione del tasso di richieste — e un corpo della risposta strutturato che identifichi il tipo di limite senza rivelare informazioni interne. Se l’operazione viene rifiutata per un’altra causa, non usare quello stato in modo fuorviante.
Fornisci indicazioni utili per recuperare, come il momento stimato per riprovare o i dati relativi al limite e al consumo definiti dal contratto. Se invii Retry-After, assicurati che indichi un tempo di attesa valido. Mantieni le risposte coerenti tra gli endpoint ed evita di esporre i contatori di altri clienti. I consumatori devono poter distinguere un rifiuto temporaneo dagli errori di autenticazione, validazione o disponibilità.
Osserva l’impatto e apporta modifiche sulla base dei dati
Registra le richieste accettate e rifiutate, l’identità o il segmento del cliente in modo sicuro, l’endpoint, la policy applicata e il motivo. Misura anche la latenza, la concorrenza e la pressione sulle dipendenze rilevanti. Non conservare credenziali né dati personali non necessari; quando bastano per l’analisi, usa identificativi protetti o aggregati.
Un aumento dei rifiuti non dimostra, da solo, che la soglia sia troppo restrittiva. Cerca schemi ricorrenti: clienti interessati, orari, endpoint, durata delle operazioni e tentativi ripetuti successivi. Indaga su possibili falsi positivi, per esempio rifiuti concentrati nelle organizzazioni con credenziali condivise o nei processi pianificati. Modifica una variabile alla volta e conserva un modo per annullare la modifica.
Introduci la policy gradualmente
Prima di applicare un limite, valuta la policy sulla base dei dati di utilizzo e prova scenari rappresentativi. Se l’architettura lo consente, registra quali richieste sarebbero state rifiutate senza bloccarle; questa osservazione non sostituisce i test di carico né garantisce che i dati storici permettano di prevedere tutti i picchi.
- Definisci il rischio che vuoi controllare e se è opportuno un limite al tasso di richieste, una quota, un limite di concorrenza o una combinazione.
- Assegna i limiti per identità e risorsa e verifica l’isolamento tra utenti e organizzazioni.
- Prova picchi, operazioni lente, tentativi ripetuti, credenziali condivise e guasti dell’archivio dei contatori.
- Verifica che più istanze applichino il limite in modo coordinato e che lo stato temporaneo venga ripulito.
- Convalida la risposta di rifiuto, le indicazioni per riprovare e la compatibilità con i consumatori attuali.
- Monitora i rifiuti, la latenza e le dipendenze; comunica le modifiche che possono influire sulle integrazioni.
I limiti di consumo nelle API PHP devono proteggere sia la piattaforma sia la continuità operativa dei clienti. La policy migliore non è la più restrittiva, ma quella che controlla il rischio con regole che consentono di attribuire i consumi, risposte prevedibili e dati sufficienti per correggere gli effetti indesiderati.
