Enxugar respostas de API para uma UX móvel mais rápida: passos práticos

Como respostas de API “inchadas” aparecem no móvel

No celular, respostas de API inchadas se mostram como telas lentas que ficam presas no spinner, mesmo em um Wi‑Fi razoável. Em conexões mais fracas o atraso fica evidente: toques parecem lentos e o scroll da lista pode travar enquanto o app espera os dados.

A causa é simples. O app baixa mais dados do que precisa para renderizar a tela. Esse JSON extra ainda precisa viajar pela rede, ser parseado e ocupar memória. Se a UI nunca mostra a maior parte dele, o usuário paga um custo sem benefício.

O inchaço costuma se esconder em alguns lugares:

• Objetos profundamente aninhados que pertencem a outras telas (por exemplo, perfis completos de usuário dentro de cada comentário)
• Grandes arrays buscados “por precaução” (500 itens quando a tela mostra 20)
• Campos repetidos copiados em muitos itens (o mesmo objeto de categoria dentro de cada produto)
• Campos pesados que somam rápido (descrições longas, HTML, metadados de imagem, logs de auditoria)

Imagine uma tela de catálogo que mostra nome do produto, preço, miniatura e “em estoque”. Se a resposta também inclui detalhes completos do vendedor, produtos relacionados por item e avaliações, a primeira pintura fica mais lenta sem benefício visível.

O objetivo não é deixar respostas minúsculas a todo custo. É enviar o menor payload que ainda abasteça a tela, e nada além. Feito consistentemente, a UX móvel costuma ficar mais rápida sem mudar a UI.

Por que payloads menores normalmente significam UX móvel mais rápida

No móvel, a velocidade muitas vezes é limitada pela rede, não pelo telefone. Uma resposta que parece aceitável no Wi‑Fi do escritório pode parecer lenta no celular, onde largura de banda cai e latência aumenta conforme o usuário se move ou perde sinal.

O tamanho atrapalha de várias maneiras. Respostas maiores demoram mais para baixar, e sofrem mais quando pacotes são perdidos e precisam de retransmissão. A tela espera mais tempo antes de mostrar algo útil.

Há também custo de bateria e CPU. Mais bytes significam mais tempo de rádio e mais trabalho para decodificar e parsear JSON. Em telefones de entrada, parsear objetos aninhados grandes pode ficar perceptível, especialmente se competir com o trabalho da UI.

Sintomas típicos:

• Primeira renderização mais lenta porque o app espera o payload completo
• Toques e rolagem atrasados se o parsing competir com o trabalho da UI
• Mais estados de “carregando” enquanto o app remodela dados
• Mais falhas e timeouts em conexões ruins

O servidor também sente. Payloads maiores aumentam custos de banda e reduzem throughput, já que cada requisição demora mais para construir, serializar e enviar. Respostas mais enxutas costumam melhorar tanto a performance do cliente quanto a eficiência do servidor.

Encontre o que seu app não está usando (auditoria simples)

Escolha uma tela lenta ou que consome muitos dados. Uma única tela já é suficiente para revelar padrões que você pode aplicar em toda a API.

Primeiro, escreva literalmente o que a tela mostra. Se ela exibe título, preço, miniatura e um badge de “em estoque”, esses são os campos que importam para essa visão.

Depois compare essa lista com a resposta real que o app recebe (inspector de rede, ferramenta proxy ou logs do servidor). É aqui que o inchaço costuma ficar óbvio: grandes objetos retornam “por precaução”, mesmo que a tela nunca os use.

Uma auditoria rápida que você pode fazer em 15 minutos:

• Capture uma resposta real para essa tela (não um mock).
• Destaque os campos que a tela usa agora.
• Marque campos que nunca são usados nessa tela (especialmente objetos aninhados).
• Identifique as partes pesadas: arrays longos, includes profundos, grandes blobs de metadata.
• Decida o que fica agora, o que se move para uma chamada posterior e o que é removido.

Padrões que valem questionar incluem um objeto de usuário completo anexado a cada item, includes profundos como order -\u003e customer -\u003e addresses -\u003e ..., e objetos de “metadata” que crescem com o tempo. Outro sinal de alerta é enviar tanto uma versão resumo quanto uma detalhada do mesmo conteúdo quando a tela mostra apenas uma.

Escreva as decisões. Essa nota curta vira seu plano de mudanças e reduz o risco de cortar algo que outra tela realmente precisa.

Ganhos rápidos: elimine objetos aninhados e listas pesadas

Vencedores rápidos geralmente vêm de parar “coisas extras” na origem. Se uma tela só precisa de nome e status, devolver um objeto de perfil aninhado completo (configurações, permissões, logs de auditoria, timestamps) é desperdício em cada requisição.

Uma regra prática: substitua includes profundos por identificadores mais um pequeno resumo. Em vez de embutir um customer completo em cada order, retorne customerId e alguns campos que a UI realmente mostra (como customerName). Busque detalhes completos do cliente quando o usuário abrir a página do cliente.

Includes padrão são outro problema comum. Objetos relacionados são adicionados “temporariamente” e nunca removidos. Se a tela não mostra, não envie.

Remova também campos que não deveriam sair do servidor, como strings de debug, flags internas que o cliente não usa, valores computados duplicados, campos antigos mantidos após um refactor e grandes blobs (HTML/markdown/base64) quando um preview curto é suficiente.

Listas pesadas costumam ser os maiores motores de payload. Limite e pagine. Um padrão comum é “top N mais um count”: retorne topReviews (primeiras 3) e reviewCount, e só carregue a lista completa na tela de avaliações.

Passo a passo: adicionar seleção de campos sem quebrar clientes

A seleção de campos é uma maneira limpa de enxugar respostas sem forçar uma grande reescrita. A regra principal é compatibilidade retroativa: versões antigas do app devem continuar funcionando.

Um padrão de rollout seguro

Comece com uma abordagem:

• Allowlist de campos por endpoint (melhor quando você quer controle rígido)
• Um parâmetro de query fields= (melhor quando telas diferentes precisam de formatos diferentes)

Depois faça o rollout:

1. Mantenha defaults seguros. Se um cliente não enviar fields, retorne a mesma resposta de hoje.
2. Torne fields opcional. Exemplo: GET /products?fields=id,name,price,thumbnailUrl.
3. Forneça alguns conjuntos nomeados de campos para telas comuns. Mesmo que você use fields=, documente o que “home”, “list” e “details” geralmente solicitam.
4. Entregue o suporte no servidor primeiro, depois atualize o app. Clientes antigos continuam recebendo o payload padrão.
5. Meça, então ajuste. Depois que a maioria dos usuários estiver na nova versão, considere reduzir a resposta padrão (ou mantenha se precisar suportar clientes antigos).

Campos aninhados: mantenha regras simples

A seleção aninhada é onde a complexidade aparece. Você pode manter seleção plana (apenas nível superior) ou permitir um formato aninhado pequeno com regras rígidas.

Um formato simples é: fields=id,name,price,category(id,name). Se isso for demais, use include= para relacionamentos (exemplo: include=category) e mantenha fields apenas no nível superior.

Adicione validação para que a seleção de campos não exponha dados que você nunca quis retornar:

• Rejeite campos desconhecidos com um erro claro
• Bloqueie campos sensíveis (segredos, notas internas, tokens brutos)
• Limite profundidade e número de campos para prevenir consultas caras
• Permita apenas campos que você explicitamente allowlistou

Uma configuração prática é: telas de lista pedem id,name,price,thumbnailUrl, e telas de detalhe adicionam description,images,availability. Mesmo recurso, payloads menores onde importa.

Modele endpoints para lista vs visualização detalhada

Uma razão comum para telas móveis parecerem lentas é que endpoints de lista agem como “me dê tudo”. Um feed só precisa de dados suficientes para renderizar linhas rapidamente. Guarde dados mais profundos para a tela que abre o item.

Um padrão simples é ter duas formas:

• Resumo para listas (pequeno, previsível, rápido)
• Detalhe para um único item (maior, completo)

Torne endpoints de lista intencionalmente pequenos

Para listas e feeds, retorne apenas o que a UI mostra na lista: id, título, URL da miniatura pequena, status curto e um ou dois atributos chave.

Mantenha listas limitadas e pagine por padrão, mesmo se os conjuntos de dados “normalmente” permanecerem pequenos. Use paginação page+limit ou cursor e inclua um next pointer claro.

Cuidado com totais. Um total pode ser caro se exigir trabalho extra. Se a UI só precisa de “carregar mais”, um simples hasNext frequentemente basta.

E não retorne histórico completo por padrão. Logs, mensagens, eventos e trilhas de auditoria crescem indefinidamente. Retorne a página mais recente e pagine.

Reserve dados pesados para endpoints de detalhe

Endpoints de detalhe podem incluir objetos aninhados, descrições longas e registros relacionados porque são chamados com menos frequência.

Exemplo: GET /products retorna apenas campos de resumo. Quando o usuário toca um produto, GET /products/{id} retorna variantes, imagens completas, avaliações e regras de inventário. Se precisar de mais flexibilidade depois, adicione seleção de campos opcional, mas mantenha defaults de lista pequenos e estáveis.

Noções básicas de compressão e cache (mantenha simples)

Compressão e cache são boas melhorias “depois”. Compressão torna cada viagem menor. Cache evita a viagem.

Compressão: quando ajuda (e quando não ajuda)

Ative gzip ou brotli para respostas JSON. Compressão ajuda mais quando respostas são textuais e repetitivas (com chaves JSON repetidas e valores repetidos). Em redes móveis lentas, pode reduzir bastante o tempo de transferência.

Compressão ajuda menos quando respostas já são mínimas, já estão comprimidas (imagens, PDFs) ou quando seu servidor é limitado em CPU. Se sua resposta média tem 2–5 KB, compressão raramente é o gargalo principal.

Uma regra simples: comprima JSON por padrão e mantenha-o simples.

Cache: evite re-download do que não mudou

Cache pode trazer grande ganho porque muitas telas reutilizam os mesmos dados (categorias, feature flags, configurações do usuário, países de envio). Faça cache agressivo de dados estáveis e atualize apenas quando mudarem.

Mantenha regras de cache previsíveis:

• Faça cache de dados de referência com um gatilho de atualização claro (atualização do app, refresh manual ou um número de versão)
• Armazene configurações do usuário até que ele as altere
• Não faça cache de feeds muito pessoais ou que mudam rápido, a menos que tenha um plano de invalidação claro

Para evitar re-downloads, suporte requisições condicionais (por exemplo, ETags). O servidor retorna um ETag; o cliente envia de volta na próxima vez. Se nada mudou, o servidor responde 304 Not Modified sem corpo.

Se você herdou um backend gerado por IA, cache e compressão costumam ser ajustes mais seguros depois de remover overfetching acidental e formatos inconsistentes de resposta.

Um exemplo realista: enxugando a resposta de uma tela de catálogo

Imagine uma lista de produtos. Cada linha mostra nome, preço, uma miniatura pequena e um badge de estoque. Só isso. Mas a API retorna o objeto de produto inteiro, mais dados relacionados que a tela nunca toca.

Antes (inchaço comum): o endpoint de lista retorna descrições completas, todas as imagens em vários tamanhos, perfis de vendedor, corpos de avaliações e metadata extra. No celular, isso significa mais bytes para baixar, mais JSON para parsear e mais tempo até a lista ficar responsiva.

{
  "products": [
    {
      "id": "p_123",
      "name": "Trail Running Shoes",
      "price": 89.99,
      "thumbnail": {"url": "...", "w": 200, "h": 200},
      "stock": {"status": "in_stock", "count": 42},
      "description": "...long text...",
      "images": [{"url": "..."}, {"url": "..."}],
      "seller": {"id": "s_9", "name": "...", "bio": "...", "payout_settings": "..."},
      "reviews": {"avg": 4.7, "items": [{"body": "..."}]}
    }
  ]
}

Depois (resposta enxuta para lista): retorne apenas o que a lista precisa, mais um id estável para a chamada de detalhe.

{
  "products": [
    {
      "product_id": "p_123",
      "name": "Trail Running Shoes",
      "price": 89.99,
      "thumbnail_url": "...",
      "stock_badge": "in_stock"
    }
  ]
}

Quando o usuário toca um item, a tela de detalhe busca o resto (imagens completas, descrição, perfil do vendedor, avaliações). A lista carrega mais rápido e tende a rolar melhor porque o app gasta menos tempo esperando e parseando.

Erros comuns e armadilhas para evitar

A maneira mais rápida de perder os benefícios do enxugamento é lançá‑lo sem salvaguardas. A maioria dos problemas aparece em produção, onde versões antigas do app e dados reais colidem.

Um erro comum é adicionar seleção de campos tornando dados privados selecionáveis. Trate seleção como uma allowlist, não como um espelho das colunas do banco. Se um campo é sensível (tokens, notas internas, preço de custo, flags de admin), nunca deve ser selecionável.

Outra armadilha é quebrar builds móveis antigas mudando defaults muito agressivamente. Se ontem a resposta sempre incluía name e price, não exija de repente fields=name,price para obtê‑los.

Cortar demais também pode causar N+1. Se uma tela mostra 20 itens e cada item agora precisa de uma chamada posterior para informação básica, o tempo total pode piorar no móvel. Busque “uma chamada por tela” quando prático: um payload de lista pequeno que ainda contenha tudo necessário para renderizar.

Finalmente, não esqueça do tamanho de payload de erros. Grandes stack traces, detalhes de validação repetidos e corpos de requisição espelhados podem ser maiores que suas respostas de sucesso. Mantenha erros curtos, consistentes e seguros.

Salvaguardas que funcionam:

• Use uma allowlist para campos selecionáveis
• Mantenha defaults compatíveis retroativamente
• Meça contagem de chamadas além do tamanho do payload
• Separe formas para lista e detalhe
• Limite e saneie respostas de erro

Checklist rápido antes de enviar mudanças

Antes de cortar campos ou mudar formatos, confirme o que cada tela realmente precisa. Um pequeno desencontro pode virar texto faltando, ordenação quebrada ou um crash que só aparece em redes lentas.

Verificações práticas pré‑deploy:

• Para cada tela, confirme que o app lê todos os campos que você planeja manter
• Remova campos que nenhum código toca, mas não mude o significado de campos existentes
• Coloque limites rígidos em listas grandes (paginação e tamanho máximo razoável)
• Evite objetos profundamente aninhados por padrão; retorne IDs ou pequenos resumos a menos que o cliente peça explicitamente
• Se suportar seleção de campos, use uma allowlist e nunca passe nomes brutos de campos direto para consultas ao banco

Depois meça o impacto. Registre tamanho do payload e tempo de resposta antes e depois em um dispositivo real, idealmente numa conexão lenta. Observe o tracking de erros para picos logo após o release.

Próximos passos: torne o enxugamento parte da rotina de releases

Enxugar respostas de API funciona melhor como hábito. Comece por uma tela de alto tráfego onde carregamentos lentos são mais óbvios (feed home, resultados de busca, lista de catálogo), enxugue esse endpoint, meça o impacto e repita.

Defina metas simples para que “bom” fique claro:

• Telas de lista: respostas pequenas que carreguem rápido no celular
• Telas de detalhe: mais dados, mas só o que a UI realmente precisa
• Respostas de erro: pequenas e consistentes

Quando precisar de flexibilidade, mantenha a seleção de campos previsível: um parâmetro único e um pequeno conjunto de campos conhecidos ou presets nomeados.

Se você herdou um backend gerado por IA, tome cuidado: mudanças de resposta muitas vezes convivem com lógica emaranhada ou armadilhas de segurança (como segredos expostos ou injeção SQL). FixMyMess (fixmymess.ai) foca em diagnosticar e reparar codebases gerados por IA e pode checar formatos de resposta, autenticação e endurecimento de segurança antes de você lançar mudanças.