--- term: 'API Payload Optimization' seoTitle: 'API Payload Optimization: Smaller, Faster Responses' headline: 'What is API Payload Optimization?' slug: api-payload-optimization category: api-realtime shortDefinition: 'API payload optimization is a practice of shrinking what an API sends — fewer fields, smaller pages, compression — so responses load fast.' relatedTerms: - overfetching-underfetching - graphql-vs-rest - n-plus-one-query-problem - api-rate-limiting-throttling - cdn-content-delivery-network contrastsWith: - overfetching-underfetching faq: - question: 'What is API payload optimization?' answer: 'The practice of minimizing what an API response carries: selecting only needed fields, paginating lists, compressing the bytes on the wire, and skipping transfers entirely when the client already has the data. The goal is user-visible — faster screens, especially on mobile networks — and operational: less bandwidth, lighter servers, smaller bills.' - question: 'How do I reduce API response size?' answer: 'In impact order: select fields — most responses carry far more than the screen renders; paginate — bound every list; compress — standard encodings shrink JSON by 70–90% for nearly free; and cache-validate — a 304 Not Modified transfers almost nothing. The first two shrink the real payload; the last two shrink the wire.' - question: 'How much does compression reduce JSON size?' answer: 'JSON is repetitive text, which compressors love: 70–90% reductions are routine, with modern encodings a further slice better than the classic one. Two caveats: compression shrinks transfer, not parsing — a 2 MB response is still 2 MB of parsing after decompression — and payloads under about a kilobyte are not worth compressing.' - question: 'What is a sparse fieldset?' answer: 'Asking for specific fields instead of whole resources — a fields parameter in REST conventions, select() in SDK query builders, or the query itself in GraphQL. It attacks overfetching at the source: a list screen needing three fields has no business receiving forty per row.' - question: 'What is a good API payload size?' answer: 'Working budgets from mobile practice: under ~50 KB for list responses, under ~20 KB for a single resource, under ~10 KB for anything on the critical rendering path — all measured compressed, on the wire. Budgets matter less for their exact numbers than for existing: what gets measured against a budget stays small.' - question: 'Does payload size really affect latency?' answer: 'Directly, and more than intuition suggests on mobile: transfer time scales with bytes over constrained bandwidth, large payloads span multiple round trips as connections ramp up, and parsing cost lands on low-power devices. Payload size feeds time-to-first-byte and largest-contentful-paint — it is a user-experience metric wearing a backend disguise.' - question: 'How do ETags and 304 responses work?' answer: 'The server tags a response with a version fingerprint; the client sends it back on the next request; unchanged content earns a 304 Not Modified with an empty body — the cheapest payload optimization there is: not sending the payload. It pairs naturally with data that reads often and changes rarely.' - question: 'Offset or cursor pagination for large lists?' answer: 'Cursors, for anything deep or live: constant cost at any depth and stability under concurrent writes, where offsets slow linearly and can skip or duplicate rows as data shifts. Offsets stay legitimate for shallow, page-numbered admin views. Either way, unpaginated lists are the payload bug that grows with your success.' 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: 'Lean payloads by default' text: 'Back4app SDKs make the two biggest optimizations one-liners: select() ships only the fields the screen needs, limit() bounds every page — over compressed, cache-friendly APIs the platform serves for you.' linkText: 'Start building free' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-07-27' translationKey: api-payload-optimization --- **API payload optimization is a practice of shrinking what an API sends — fewer fields, smaller pages, compression — so responses load fast.** It is the backend's share of frontend performance: every needless kilobyte an API ships is paid for again on every device, every network, every render — and the biggest wins are usually one parameter away. ## Key takeaways | Question | Answer | | --- | --- | | The big four | Field selection · pagination · compression · cache validation | | Impact order | Select and paginate shrink the data; compress and 304 shrink the wire | | The budgets | ~50 KB lists · ~20 KB single resource · ~10 KB critical path (compressed) | | The measure | Content-Length in DevTools or curl — then tie it to TTFB and LCP | | The trap | Compression hides bloat: transfer shrinks, parsing does not | ## A worked example: 85 KB → 4 KB ```text GET /articles → 85.5 KB (50 full rows, 40 fields each) 1 · Select fields the screen shows GET /articles?fields=title,summary,publishedAt → 15.5 KB (-82%: overfetching gone) 2 · Paginate to what's visible …&limit=20 → 6.2 KB (bounded page) 3 · Compress on the wire Content-Encoding: br → ~1.4 KB transferred (-77% again) 4 · Revalidate on revisit If-None-Match: "v42" → 304 → ~0.1 KB (nothing changed, nothing sent) ``` Steps 1 and 2 as application code — the SDK idiom that makes lean the default: **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) } ``` ## Where the bytes and milliseconds go ```mermaid flowchart LR accTitle: Where API response time accrues accDescr: A response's latency accumulates through query execution, serialization of selected fields, compression, transfer over the network scaled by payload size, and client-side parsing and rendering. Q["Query
(select less → do less)"] --> S["Serialize
fields × rows"] S --> C["Compress
70–90% off the wire"] C --> T["Transfer
bytes ÷ bandwidth — the mobile tax"] T --> P["Parse + render
uncompressed size returns here"] ``` The diagram carries the two honest footnotes. **Compression is transfer-only:** the client parses the *decompressed* bytes, so structural trimming (fields, pages) beats compression alone — they compound, in that order. **Transfer is where mobile suffers:** constrained bandwidth and connection ramp-up make big payloads span multiple round trips, which is how backend JSON becomes a frontend LCP problem. ## API payload reduction techniques, ranked | Technique | Typical cut | Effort | Fine print | | --- | --- | --- | --- | | Field selection / [sparse fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets) | 30–80% | One parameter | Screens change — keep selections honest | | Pagination (bounded pages) | Unbounded → bounded | One parameter | Cursors for depth; offsets for shallow admin | | Compression ([Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding)) | 70–90% of transfer | Server config | Skip under ~1 KB; parsing unaffected | | [ETags / 304](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag) | ~100% on unchanged | Moderate | Best for read-often, change-rarely | | Batching requests | Round trips, not bytes | Moderate | Cousin of the [N+1 fix](/glossary/n-plus-one-query-problem/) | | Binary formats | 60–80% vs. raw JSON | High | Tooling and debuggability tax — for internal hot paths | | Delta sync | Only what changed | High | The endgame for offline-first apps | ## Measuring: the missing discipline Most payload bloat survives because nobody looks. The audit is one flag: `curl -so /dev/null -w '%{size_download}'` per endpoint (or the size column in browser dev tools — noting *transferred* vs. *resource* size, which is your compression ratio). Put the numbers against the budgets — 50/20/10 KB compressed for lists, single resources, critical path — and wire the check into CI for the endpoints that matter. Payloads, like queries, regress silently under feature pressure; budgets are how "one more field" meets a number instead of a shrug. ## Common use cases - **Mobile list screens** — the canonical win: forty-field rows trimmed to the three the cell renders. - **Slow-network markets** — payload discipline is accessibility; budgets are how you respect a 3G user. - **High-traffic APIs** — bytes × requests × egress pricing: payload cuts are literal invoice cuts. - **Dashboard aggregations** — computed summaries server-side instead of shipping raw rows to sum in the browser. - **Offline-first sync** — delta payloads and validators, so reconnecting clients fetch changes, not worlds. ## Which technique first? A decision matrix | Symptom | Reach for | | --- | --- | | Responses carry fields no screen shows | Field selection — today | | Lists grow with your user count | Pagination with cursors | | Transfer is large but data is right | Compression config | | Clients re-fetch unchanged data | ETags and 304s | | Many small sequential calls | Batching / includes | | Internal service chat dominates | Binary formats, measured first | The ordering rule: **structural before wire** — fix what you send before optimizing how it travels; compression applied to bloat is bloat with a bow on it. ## Limitations and trade-offs - **Selection couples clients to fields.** Sparse fieldsets that drift from the UI cause missing-data bugs; generated types and code review keep selections honest. - **Caching adds correctness work.** Validators must actually change when data does; a stale 304 is a bug wearing an optimization's badge. - **Binary formats tax humans.** Wire savings against every debugging session that can no longer read the traffic — usually an internal-path trade only. - **Compression costs CPU** — trivially at moderate levels, measurably at maximums; tune, don't max. - **Optimization can hide modeling problems.** If every screen needs deep trimming, the API's shapes may be wrong — sometimes the fix is [the query model](/glossary/graphql-vs-rest/), not the diet. ## Payload optimization on Back4app Back4app is an open-source Backend-as-a-Service (BaaS) platform that combines a managed database, auto-generated REST and GraphQL APIs, authentication, file storage, and Cloud Code serverless functions. The two highest-impact techniques are SDK one-liners — [`select()` and `limit()`](https://docs.parseplatform.org/js/guide/#queries) in the code tabs above — with GraphQL field selection available when clients want to shape responses themselves. The wire side comes managed: compressed transfer, cache-friendly file URLs off the API path, and Cloud Code for server-side aggregation when the cheapest payload is the summary you computed before sending. Lean by idiom, not by campaign.