--- term: 'Otimização de Payload de API' seoTitle: 'Otimização de Payload de API: Respostas Menores e Mais Rápidas' headline: 'O que é otimização de payload de API?' slug: otimizacao-de-payload category: api-realtime shortDefinition: 'Otimização de payload de API é a prática de encolher o que uma API envia — menos campos, páginas menores, compressão — para as respostas carregarem rápido.' relatedTerms: - overfetching-underfetching - graphql-vs-rest - n-plus-one-query-problem - api-rate-limiting-throttling - cdn-content-delivery-network contrastsWith: - overfetching-underfetching faq: - question: 'O que é otimização de payload de API?' answer: 'É a prática de minimizar o que uma resposta de API carrega: selecionar só os campos necessários, paginar listas, comprimir os bytes na rede e pular a transferência quando o cliente já tem os dados. O objetivo é visível para o usuário — telas mais rápidas, sobretudo em redes móveis — e operacional: menos banda, servidores mais leves, faturas menores.' - question: 'Como reduzir o tamanho da resposta de uma API?' answer: 'Em ordem de impacto: selecione campos — a maioria das respostas carrega muito mais do que a tela renderiza; pagine — limite toda lista; comprima — encodings padrão encolhem JSON em 70–90% quase de graça; e revalide o cache — um 304 Not Modified transfere quase nada. As duas primeiras encolhem o payload real; as duas últimas encolhem a transmissão.' - question: 'Quanto a compressão reduz o tamanho de um JSON?' answer: 'JSON é texto repetitivo, e compressores adoram isso: reduções de 70–90% são rotina, com os encodings modernos ganhando mais uma fatia sobre o clássico. Duas ressalvas: compressão encolhe a transferência, não o parsing — uma resposta de 2 MB continua sendo 2 MB de parsing após a descompressão — e payloads abaixo de cerca de um kilobyte não valem a compressão.' - question: 'O que é um sparse fieldset?' answer: 'É pedir campos específicos em vez de recursos inteiros — um parâmetro fields nas convenções REST, select() nos query builders dos SDKs ou a própria query no GraphQL. Ataca o overfetching na origem: uma tela de lista que precisa de três campos não tem por que receber quarenta por linha.' - question: 'Qual é um bom tamanho de payload de API?' answer: 'Orçamentos de trabalho vindos da prática mobile: abaixo de ~50 KB para respostas de lista, abaixo de ~20 KB para um recurso único, abaixo de ~10 KB para qualquer coisa no caminho crítico de renderização — sempre medidos comprimidos, na rede. Os orçamentos importam menos pelos números exatos do que por existirem: o que é medido contra um orçamento permanece pequeno.' - question: 'O tamanho do payload realmente afeta a latência?' answer: 'Diretamente, e mais do que a intuição sugere no mobile: o tempo de transferência escala com bytes sobre banda limitada, payloads grandes atravessam múltiplos round trips enquanto a conexão acelera, e o custo de parsing recai sobre dispositivos de baixa potência. O tamanho do payload alimenta o time-to-first-byte e o largest-contentful-paint — é uma métrica de experiência do usuário disfarçada de backend.' - question: 'Como funcionam ETags e respostas 304?' answer: 'O servidor marca a resposta com uma impressão digital de versão; o cliente a devolve na requisição seguinte; conteúdo inalterado ganha um 304 Not Modified com corpo vazio — a otimização de payload mais barata que existe: não enviar o payload. Combina naturalmente com dados que são lidos com frequência e mudam raramente.' - question: 'Paginação por offset ou por cursor para listas grandes?' answer: 'Cursores, para qualquer coisa profunda ou viva: custo constante em qualquer profundidade e estabilidade sob escritas concorrentes, onde offsets desaceleram linearmente e podem pular ou duplicar linhas conforme os dados mudam. Offsets seguem legítimos para telas administrativas rasas com números de página. De um jeito ou de outro, listas sem paginação são o bug de payload que cresce com o seu sucesso.' 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: 'Payloads enxutos por padrão' text: 'Nos SDKs do Back4app, as duas maiores otimizações são one-liners: select() envia só os campos que a tela precisa, limit() limita cada página — sobre APIs comprimidas e amigáveis a cache que a plataforma serve por você.' linkText: 'Comece grátis' linkUrl: 'https://www.back4app.com/signup' author: 'Back4app Engineering' publishedDate: '2026-08-24' translationKey: api-payload-optimization --- **Otimização de payload de API é a prática de encolher o que uma API envia — menos campos, páginas menores, compressão — para as respostas carregarem rápido.** É a fatia do backend na performance do frontend: cada kilobyte desnecessário que uma API envia é pago de novo em cada dispositivo, cada rede, cada renderização — e as maiores vitórias geralmente estão a um parâmetro de distância. ## Principais pontos | Pergunta | Resposta | | --- | --- | | As quatro grandes | Seleção de campos · paginação · compressão · validação de cache | | Ordem de impacto | Selecionar e paginar encolhem os dados; comprimir e 304 encolhem a transmissão | | Os orçamentos | ~50 KB listas · ~20 KB recurso único · ~10 KB caminho crítico (comprimidos) | | A medida | Content-Length no DevTools ou curl — depois amarre a TTFB e LCP | | A armadilha | Compressão esconde inchaço: a transferência encolhe, o parsing não | ## Um exemplo prático: 85 KB → 4 KB ```text GET /articles → 85.5 KB (50 linhas completas, 40 campos cada) 1 · Selecione os campos que a tela mostra GET /articles?fields=title,summary,publishedAt → 15.5 KB (-82%: overfetching eliminado) 2 · Pagine para o que está visível …&limit=20 → 6.2 KB (página limitada) 3 · Comprima na transmissão Content-Encoding: br → ~1.4 KB transferidos (-77% de novo) 4 · Revalide na próxima visita If-None-Match: "v42" → 304 → ~0.1 KB (nada mudou, nada enviado) ``` Os passos 1 e 2 como código de aplicação — o idioma de SDK que torna o enxuto o padrão: **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) } ``` ## Para onde vão os bytes e os milissegundos ```mermaid flowchart LR accTitle: Onde o tempo de resposta da API se acumula accDescr: A latência de uma resposta se acumula na execução da query, na serialização dos campos selecionados, na compressão, na transferência pela rede proporcional ao tamanho do payload e no parsing e renderização no cliente. Q["Query
(selecione menos → faça menos)"] --> S["Serializar
campos × linhas"] S --> C["Comprimir
70–90% a menos na rede"] C --> T["Transferir
bytes ÷ banda — o imposto mobile"] T --> P["Parsear + renderizar
o tamanho descomprimido volta aqui"] ``` O diagrama carrega as duas notas honestas. **Compressão é só transferência:** o cliente parseia os bytes *descomprimidos*, então o corte estrutural (campos, páginas) vence a compressão sozinha — eles se compõem, nessa ordem. **Transferência é onde o mobile sofre:** banda limitada e a aceleração gradual da conexão fazem payloads grandes atravessarem múltiplos round trips — é assim que JSON de backend vira problema de LCP no frontend. ## Técnicas de redução de payload de API, ranqueadas | Técnica | Corte típico | Esforço | Letra miúda | | --- | --- | --- | --- | | Seleção de campos / [sparse fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets) | 30–80% | Um parâmetro | Telas mudam — mantenha as seleções honestas | | Paginação (páginas limitadas) | Ilimitado → limitado | Um parâmetro | Cursores para profundidade; offsets para admin raso | | Compressão ([Content-Encoding](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Content-Encoding)) | 70–90% da transferência | Config de servidor | Pule abaixo de ~1 KB; parsing não muda | | [ETags / 304](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/ETag) | ~100% quando inalterado | Moderado | Melhor para lê-muito, muda-pouco | | Batching de requisições | Round trips, não bytes | Moderado | Primo da [solução do N+1](/glossary/pt/problema-n-mais-1/) | | Formatos binários | 60–80% vs. JSON puro | Alto | Imposto de tooling e depuração — para caminhos internos quentes | | Delta sync | Só o que mudou | Alto | O fim de jogo para apps offline-first | ## Medição: a disciplina que falta A maior parte do inchaço de payload sobrevive porque ninguém olha. A auditoria é uma flag: `curl -so /dev/null -w '%{size_download}'` por endpoint (ou a coluna de tamanho nas ferramentas de desenvolvedor do navegador — observando *transferred* vs. *resource* size, que é a sua taxa de compressão). Coloque os números contra os orçamentos — 50/20/10 KB comprimidos para listas, recursos únicos e caminho crítico — e ligue a checagem ao CI para os endpoints que importam. Payloads, como queries, regridem em silêncio sob pressão de features; orçamentos são como "só mais um campo" encontra um número em vez de dar de ombros. ## Casos de uso comuns - **Telas de lista no mobile** — a vitória canônica: linhas de quarenta campos aparadas para os três que a célula renderiza. - **Mercados de rede lenta** — disciplina de payload é acessibilidade; orçamentos são como você respeita um usuário em 3G. - **APIs de alto tráfego** — bytes × requisições × preço de egresso: cortes de payload são cortes literais de fatura. - **Agregações de dashboard** — resumos computados no servidor em vez de enviar linhas brutas para somar no navegador. - **Sync offline-first** — payloads delta e validadores, para clientes que reconectam buscarem mudanças, não mundos. ## Qual técnica primeiro? Matriz de decisão | Sintoma | Recorra a | | --- | --- | | Respostas carregam campos que nenhuma tela mostra | Seleção de campos — hoje | | Listas crescem com a sua base de usuários | Paginação com cursores | | Transferência grande, mas dados corretos | Config de compressão | | Clientes rebuscam dados inalterados | ETags e 304s | | Muitas chamadas pequenas sequenciais | Batching / includes | | Conversa entre serviços internos domina | Formatos binários, medidos antes | A regra de ordenação: **estrutural antes da transmissão** — conserte o que você envia antes de otimizar como viaja; compressão aplicada a inchaço é inchaço com laço de presente. ## Limitações e trade-offs - **Seleção acopla clientes a campos.** Sparse fieldsets que derivam da UI causam bugs de dados faltantes; tipos gerados e code review mantêm as seleções honestas. - **Cache adiciona trabalho de corretude.** Validadores precisam realmente mudar quando os dados mudam; um 304 obsoleto é um bug usando o crachá de uma otimização. - **Formatos binários taxam humanos.** Pese a economia de rede contra cada sessão de depuração que não consegue mais ler o tráfego — geralmente uma troca só para caminhos internos. - **Compressão custa CPU** — trivialmente em níveis moderados, mensuravelmente nos máximos; ajuste, não maximize. - **Otimização pode esconder problemas de modelagem.** Se toda tela precisa de cortes profundos, os formatos da API podem estar errados — às vezes a solução é [o modelo de consulta](/glossary/pt/graphql-vs-rest/), não a dieta. ## Otimização de payload no Back4app O Back4app é uma plataforma open-source de Backend as a Service (BaaS) que combina banco de dados gerenciado, APIs REST e GraphQL geradas automaticamente, autenticação, armazenamento de arquivos e funções serverless com Cloud Code. As duas técnicas de maior impacto são one-liners de SDK — [`select()` e `limit()`](https://docs.parseplatform.org/js/guide/#queries) nas abas de código acima — com seleção de campos via GraphQL disponível quando os clientes querem moldar as respostas eles mesmos. O lado da transmissão vem gerenciado: transferência comprimida, URLs de arquivo amigáveis a cache fora do caminho da API e Cloud Code para agregação no servidor quando o payload mais barato é o resumo que você computou antes de enviar. Enxuto por idioma, não por campanha.