--- term: 'Ottimizzazione del payload delle API' seoTitle: 'Ottimizzazione del payload API: risposte più leggere e veloci' headline: 'Che cos''è l''ottimizzazione del payload delle API?' slug: ottimizzazione-del-payload category: api-realtime shortDefinition: 'L''ottimizzazione del payload delle API è una pratica che riduce ciò che un''API invia – meno campi, pagine limitate, compressione – per risposte rapide.' relatedTerms: - overfetching-underfetching - graphql-vs-rest - n-plus-one-query-problem - api-rate-limiting-throttling - cdn-content-delivery-network contrastsWith: - overfetching-underfetching faq: - question: 'Che cos''è l''ottimizzazione del payload delle API?' answer: 'La pratica di ridurre al minimo ciò che una risposta di API trasporta: selezionare solo i campi necessari, paginare gli elenchi, comprimere i byte in transito ed evitare del tutto il trasferimento quando il client possiede già i dati. L''obiettivo è visibile all''utente – schermate più rapide, soprattutto su rete mobile – ed è operativo: meno banda, server meno carichi, fatture più leggere.' - question: 'Come si riduce la dimensione di una risposta di API?' answer: 'In ordine di impatto: selezionare i campi – la maggior parte delle risposte trasporta molto più di ciò che la schermata mostra; paginare – limitare ogni elenco; comprimere – le codifiche standard riducono il JSON del 70–90 % a costo quasi nullo; e rivalidare la cache – un 304 Not Modified non trasferisce quasi nulla. Le prime due misure riducono il payload reale; le ultime due riducono ciò che transita in rete.' - question: 'Di quanto la compressione riduce la dimensione del JSON?' answer: 'Il JSON è testo ripetitivo, ed è proprio quello che i compressori adorano: riduzioni del 70–90 % sono normali, e le codifiche moderne guadagnano ancora un po'' su quella classica. Due riserve: la compressione riduce il trasferimento, non il parsing – una risposta da 2 MB resta 2 MB di parsing dopo la decompressione – e per i payload sotto il kilobyte la compressione non vale la pena.' - question: 'Che cos''è uno sparse fieldset?' answer: 'La richiesta di campi precisi anziché di risorse intere – un parametro fields nelle convenzioni REST, select() nei query builder degli SDK, oppure la query stessa in GraphQL. Attacca l''overfetching alla radice: una schermata di elenco che ha bisogno di tre campi non ha alcun motivo di riceverne quaranta per riga.' - question: 'Qual è una buona dimensione per il payload di un''API?' answer: 'Budget di lavoro che vengono dalla pratica mobile: sotto i ~50 KB per le risposte di elenco, sotto i ~20 KB per una singola risorsa, sotto i ~10 KB per tutto ciò che sta sul percorso critico di rendering – sempre misurati compressi, in transito. I budget contano meno per le cifre esatte che per il fatto di esistere: ciò che viene misurato contro un budget resta piccolo.' - question: 'La dimensione del payload influisce davvero sulla latenza?' answer: 'In modo diretto, e più di quanto l''intuizione suggerisca su mobile: il tempo di trasferimento cresce col numero di byte su una banda limitata, i payload grandi si distendono su più round trip mentre la connessione sale di regime, e il costo del parsing ricade su dispositivi poco potenti. La dimensione del payload alimenta il time-to-first-byte e il largest-contentful-paint – è una metrica di esperienza utente travestita da questione di backend.' - question: 'Come funzionano gli ETag e le risposte 304?' answer: 'Il server marca la risposta con un''impronta di versione; il client la rimanda alla richiesta successiva; un contenuto invariato ottiene un 304 Not Modified con corpo vuoto – l''ottimizzazione del payload più economica che esista: non inviare il payload. Si sposa naturalmente con i dati letti spesso e modificati raramente.' - question: 'Paginazione per offset o per cursore sugli elenchi grandi?' answer: 'Per cursore, per tutto ciò che è profondo o vivo: costo costante a qualsiasi profondità e stabilità di fronte alle scritture concorrenti, là dove gli offset rallentano in modo lineare e possono saltare o duplicare righe quando i dati si spostano. Gli offset restano legittimi per le viste di amministrazione poco profonde, numerate per pagina. In ogni caso, gli elenchi non paginati sono il bug di payload che cresce insieme al successo.' codeLanguages: [javascript, dart, swift, kotlin] externalAuthorities: - name: 'HTTP Content-Encoding — MDN Web Docs' url: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding' - name: 'HTTP ETag and conditional requests — MDN Web Docs' url: 'https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag' - name: 'JSON:API specification — sparse fieldsets' url: 'https://jsonapi.org/format/#fetching-sparse-fieldsets' - name: 'SDK query documentation' url: 'https://docs.parseplatform.org/js/guide/#queries' cta: title: 'Payload leggeri per impostazione predefinita' text: 'Con gli SDK di Back4app le due ottimizzazioni più redditizie stanno in una riga: select() invia solo i campi di cui la schermata ha bisogno, limit() limita ogni pagina – su API compresse e cache-friendly che la piattaforma serve per te.' linkText: 'Inizia gratis' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-10-19' translationKey: api-payload-optimization --- **L'ottimizzazione del payload delle API è una pratica che riduce ciò che un'API invia – meno campi, pagine limitate, compressione – per risposte rapide.** È la quota di prestazioni del frontend che spetta al backend: ogni kilobyte superfluo che un'API spedisce si paga di nuovo su ogni dispositivo, su ogni rete, a ogni rendering – e i guadagni più grandi distano di solito un solo parametro. ## Punti chiave | Domanda | Risposta | | --- | --- | | I quattro pilastri | Selezione dei campi · paginazione · compressione · validazione della cache | | L'ordine di impatto | Selezionare e paginare riducono i dati; comprimere e il 304 riducono il trasferimento | | I budget | ~50 KB per gli elenchi · ~20 KB per una risorsa · ~10 KB sul percorso critico (compressi) | | La misura | Content-Length nei DevTools o con curl – poi da collegare a TTFB e LCP | | L'insidia | La compressione nasconde il grasso: il trasferimento si riduce, il parsing no | ## Un esempio concreto: 85 KB → 4 KB ```text GET /articles → 85,5 KB (50 righe complete, 40 campi ciascuna) 1 · Selezionare i campi che la schermata mostra GET /articles?fields=title,summary,publishedAt → 15,5 KB (-82 %: overfetching eliminato) 2 · Paginare su ciò che è visibile …&limit=20 → 6,2 KB (pagina limitata) 3 · Comprimere in transito Content-Encoding: br → ~1,4 KB trasferiti (ancora -77 %) 4 · Rivalidare alla visita successiva If-None-Match: "v42" → 304 → ~0,1 KB (niente è cambiato, niente è stato inviato) ``` I passi 1 e 2 come codice applicativo – l'idioma degli SDK che rende la leggerezza il comportamento predefinito: **JavaScript:** ```javascript // JavaScript / Node.js — Back4app JS SDK // Ship the fields the screen needs — nothing else const query = new Parse.Query('Article'); query.equalTo('status', 'published'); query.select('title', 'summary', 'publishedAt'); // sparse fieldset query.limit(20); // bounded page const articles = await query.find(); // Full rows: ~14 KB each. This payload: ~0.4 KB each. Same screen. ``` **Flutter:** ```dart // Flutter / Dart — Back4app Flutter SDK // Ship the fields the screen needs — nothing else final query = QueryBuilder(ParseObject('Article')) ..whereEqualTo('status', 'published') ..keysToReturn(['title', 'summary', 'publishedAt']) // sparse fieldset ..setLimit(20); // bounded page final response = await query.query(); // Full rows vs selected fields: the mobile radio notices the difference. ``` **Swift:** ```swift // iOS / Swift — Back4app Swift SDK // Ship the fields the screen needs — nothing else let query = Article.query("status" == "published") .select("title", "summary", "publishedAt") // sparse fieldset .limit(20) // bounded page query.find { result in if case .success(let articles) = result { render(articles) } } ``` **Kotlin:** ```kotlin // Android / Kotlin — Back4app Android SDK // Ship the fields the screen needs — nothing else val query = ParseQuery.getQuery("Article") query.whereEqualTo("status", "published") query.selectKeys(listOf("title", "summary", "publishedAt")) // sparse fieldset query.limit = 20 // bounded page query.findInBackground { articles, e -> if (e == null) render(articles) } ``` ## Dove finiscono i byte e i millisecondi ```mermaid flowchart LR accTitle: Dove si accumula il tempo di risposta di un'API accDescr: La latenza di una risposta si accumula lungo l'esecuzione della query, la serializzazione dei campi selezionati, la compressione, il trasferimento in rete proporzionale alla dimensione del payload e infine il parsing e il rendering lato client. Q["Query
(selezionare meno → fare meno)"] --> S["Serializzare
campi × righe"] S --> C["Comprimere
70–90 % in meno in transito"] C --> T["Trasferire
byte ÷ banda – la tassa mobile"] T --> P["Parsing + rendering
la dimensione decompressa torna qui"] ``` Il diagramma porta con sé due note oneste. **La compressione riguarda solo il trasferimento:** il client fa il parsing dei byte *decompressi*, quindi lo sfoltimento strutturale (campi, pagine) batte la sola compressione – le due si sommano, in quest'ordine. **È nel trasferimento che il mobile soffre:** banda limitata e salita di regime della connessione fanno distendere i payload grandi su più round trip, ed è così che il JSON del backend diventa un problema di LCP lato frontend. ## Tecniche di riduzione del payload delle API, per impatto | Tecnica | Taglio tipico | Impegno | Le clausole in piccolo | | --- | --- | --- | --- | | Selezione dei campi / [sparse fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets) | 30–80 % | Un parametro | Le schermate cambiano – le selezioni vanno tenute aderenti | | Paginazione (pagine limitate) | Illimitato → limitato | Un parametro | Cursori per la profondità; offset per l'amministrazione poco profonda | | Compressione ([Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding)) | 70–90 % del trasferimento | Configurazione del server | Inutile sotto ~1 KB; il parsing resta invariato | | [ETag / 304](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag) | ~100 % se invariato | Moderato | Ideale per dati letti spesso e modificati raramente | | Raggruppamento delle richieste (batching) | Round trip, non byte | Moderato | Cugino della [correzione N+1](/glossary/it/problema-n-plus-1/) | | Formati binari | 60–80 % vs. JSON grezzo | Alto | Tassa su strumenti e debuggabilità – per gli hot path interni | | Sincronizzazione delta | Solo ciò che è cambiato | Alto | Il traguardo finale per le app offline-first | ## Misurare: la disciplina che manca La maggior parte del grasso nei payload sopravvive perché nessuno guarda. L'audit sta in una sola opzione: `curl -so /dev/null -w '%{size_download}'` per endpoint (oppure la colonna della dimensione negli strumenti di sviluppo del browser – distinguendo la dimensione *transferred* da quella *resource*, il cui rapporto è il tasso di compressione). I numeri vanno messi di fronte ai budget – 50/20/10 KB compressi per elenchi, singole risorse e percorso critico – e il controllo va integrato nella CI per gli endpoint che contano. I payload, come le query, regrediscono in silenzio sotto la pressione delle feature; i budget sono ciò che oppone una cifra, e non un'alzata di spalle, a "solo un campo in più". ## Casi d'uso tipici - **Schermate di elenco su mobile** – il guadagno canonico: righe da quaranta campi ridotte ai tre che la cella mostra. - **Mercati con rete lenta** – la disciplina sul payload è una questione di accessibilità; i budget sono il modo di rispettare chi naviga in 3G. - **API ad alto traffico** – byte × richieste × prezzo dell'egress: tagliare il payload è letteralmente tagliare la fattura. - **Aggregazioni per dashboard** – sintesi calcolate lato server anziché righe grezze spedite per essere sommate nel browser. - **Sincronizzazione offline-first** – payload delta e validatori, perché i client che si riconnettono recuperino i cambiamenti e non il mondo intero. ## Quale tecnica per prima? Matrice decisionale | Sintomo | Soluzione da preferire | | --- | --- | | Le risposte trasportano campi che nessuna schermata mostra | Selezione dei campi – da subito | | Gli elenchi crescono col numero di utenti | Paginazione per cursore | | Il trasferimento è pesante ma i dati sono giusti | Configurazione della compressione | | I client riscaricano dati invariati | ETag e 304 | | Molte chiamate piccole e sequenziali | Batching e include | | Dominano gli scambi fra servizi interni | Formati binari, dopo averli misurati | La regola d'ordine: **prima la struttura, poi il trasferimento** – conviene correggere ciò che si invia prima di ottimizzare il modo in cui viaggia; il superfluo compresso resta superfluo, solo con un fiocco sopra. ## Limiti e trade-off - **La selezione accoppia i client ai campi.** Gli sparse fieldset che divergono dall'interfaccia provocano bug di dati mancanti; tipi generati e revisione del codice tengono aderenti le selezioni. - **La cache aggiunge lavoro di correttezza.** I validatori devono cambiare davvero quando i dati cambiano; un 304 obsoleto è un bug che porta il distintivo di un'ottimizzazione. - **I formati binari tassano gli esseri umani.** Il risparmio sul trasferimento va messo in bilancia con ogni sessione di debug che non riesce più a leggere il traffico – di solito un trade-off riservato ai percorsi interni. - **La compressione costa CPU** – in modo trascurabile ai livelli moderati, in modo misurabile ai massimi; va regolata, non spinta al limite. - **L'ottimizzazione può nascondere problemi di modellazione.** Se ogni schermata esige una sfoltitura profonda, le forme dell'API sono forse sbagliate – a volte il rimedio è [il modello di query](/glossary/it/graphql-vs-rest/), non la dieta. ## L'ottimizzazione del payload su Back4app Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. Le due tecniche a più alto impatto stanno in una riga di SDK – [`select()` e `limit()`](https://docs.parseplatform.org/js/guide/#queries) nelle schede di codice qui sopra – e la selezione dei campi GraphQL è disponibile quando i client vogliono modellare da sé le risposte. Il lato del trasferimento arriva gestito: trasferimento compresso, URL dei file compatibili con la cache fuori dal percorso dell'API, e Cloud Code per l'aggregazione lato server quando il payload più economico è la sintesi calcolata prima dell'invio. Leggerezza per idioma, non per campagna.