Convenzioni
Paginazione, date, limiti e intestazioni della risposta.
Buste
Ogni risposta riuscita ha il formato { "data": ..., "request_id": "..." }. Quando segnali un problema, cita il
request_id: serve a trovare la riga corrispondente nel log.
Paginazione
Basata su cursore, mai su offset. Nella richiesta successiva, passa come cursor
il valore next_cursor della risposta precedente.
Con un offset si percorre di nuovo l’intero prefisso a ogni pagina e, peggio ancora, si SALTANO righe se viene inserito qualcosa tra due richieste. Di conseguenza, un client che sfoglia un elenco mentre vengono aggiunti elementi ne perde alcuni senza accorgersene. Con un cursore questo non succede.
Input flessibili
limit viene adeguato al limite massimo anziché essere rifiutato: se ne chiedi 500, ne ottieni 100 e la risposta indica il limite applicato. Un limite non numerico genera comunque un errore, perché è un dato errato, non una scelta intenzionale.
Le date accettano 2026-07-01 o un timestamp ISO 8601 completo. Una data senza orario nel parametro to indica la FINE di quel giorno, come si intende normalmente con «fino al 31».
Scrittura sicura
Ogni scrittura che sostituisce qualcosa può specificare cosa si aspetta di sostituire. Invia expected_hash del file o della voce che hai letto: se è cambiata nel frattempo, la modifica viene rifiutata con 409 conflict. Per pubblicare, ripristinare e annullare la pubblicazione, passa expected_generation della versione letta, così modifichi solo lo stato che hai esaminato. Entrambi i tipi di conflitto includono in error.details le informazioni necessarie per rileggere i dati.
Operazioni lunghe
Una build restituisce subito lo stato queued; continua a interrogarne lo stato finché non diventa ready, failed o cancelled. Sono tutti stati finali: interrompi le richieste quando ne compare uno.
Limiti di frequenza
Si applicano cinque limiti, a protezione di aspetti diversi: il volume di richieste per credenziale, una breve finestra di picco, il volume per IP, la registrazione dei client e, in particolare, i FALLIMENTI di autenticazione. Ogni risposta riporta nelle intestazioni il budget residuo; una risposta 429 include Retry-After.