Chiavi API, limiti di frequenza e la costruzione di un pipeline reale

L'API REST è la stessa utilizzata dall'interfaccia web. La differenza è che uno script può comportarsi in modo educato, e la piattaforma lo tratterà di conseguenza.

Chiavi

• Crea e revoca le chiavi in Impostazioni → Chiavi API.
• Limita l'ambito di ogni chiave al compito specifico: upload, letture o accesso completo.
• Ruota le chiavi senza tempi di inattività gestendone due durante un deploy.

curl -H "Authorization: Bearer $KEY" \
  -F "[email protected]" \
  https://zerostorage.net/api/files/upload

Limiti di frequenza

I limiti sono per chiave e per IP, con header di risposta che mostrano il budget rimanente. In caso di 429, rallenta utilizzando quegli header invece di una pausa fissa: il budget si ricarica continuamente.

Pattern di retry

1. Riprova 429 e 5xx con backoff esponenziale e jitter.
2. Non riprovare mai un 401 o 403: ruota la chiave invece.
3. L'idempotenza deriva dagli hash: l'invio ripetuto dello stesso file è gratuito.

Un pipeline che resiste al contatto

Le importazioni massive falliscono in modi prevedibili: il network ha interruzioni, una chiave viene ruotata a metà esecuzione e un loop ingenuo martella un server che sta ancora recuperando. Il pattern che regge è noioso: metti il lavoro in coda, esegui un piccolo numero di worker e lascia che gli header di risposta ne regolino il ritmo. Persisti l'hash di ogni elemento completato in modo che un riavvio riprenda da dove si era interrotto invece di ripetere. Quando un'esecuzione termina con errori, l'artefatto utile è un elenco di hash e codici di stato, non un file di log da leggere come un romanzo.

• Limita prima la concorrenza; aumentala solo se gli header mostrano budget residuo.
• Salva i checkpoint di avanzamento a ogni batch, non a ogni file.
• Attiva alert sul rapporto tra 429 e successi: quel rapporto è il vero segnale di salute.

Nessuna di queste cose è esotica. È la differenza tra uno script che gira una volta sul tuo laptop e un pipeline che qualcun altro può gestire senza chiederti come funziona. Scrivi il runbook mentre i modi di fallimento sono ancora freschi — quali ambiti di chiave esistono, qual è la concorrenza in stato stazionario e come appare una giornata sana di risposte — perché la persona svegliata alle 3 di notte non leggerà prima il codice sorgente.

Sfoglia la e il playground prima di collegare qualsiasi cosa in produzione.