API REST de alto desempenho: boas práticas de projeto

Aplicações de alta performance · Artigo

API REST de alto desempenho: boas práticas de projeto

Falar no WhatsApp
Resposta direta

API REST é uma interface em que sistemas trocam dados por HTTP, tratando cada item como um recurso com endereço próprio. O desempenho depende do projeto: listas paginadas, respostas enxutas, cache e compressão, limites de uso claros e chamadas que podem ser repetidas sem duplicar o efeito.

Pontos-chave

O que você leva deste artigo

  1. API REST: o que é e por que o projeto define o desempenhoUma API REST é uma interface em que sistemas conversam por HTTP, tratando cada coisa (pedido, cliente, produto) como um recurso com endereço próprio. O desempenho depende de como esses rec…Ir para a seção
  2. Paginação, filtros e campos: entregar só o necessárioPaginar é devolver uma lista em partes, com um ponto de continuação, em vez de despejar todos os registros. É a primeira defesa de uma API REST contra o crescimento dos dados.Ir para a seção
  3. Cache HTTP e compressão: não refazer o trabalhoO cache HTTP permite que navegadores e intermediários reutilizem respostas já recebidas, e a compressão reduz o tamanho do que trafega. Os dois cortam trabalho do servidor sem mudar a regr…Ir para a seção
  4. Limites de uso: proteger a API sem punir quem a usa bemLimitar a taxa de uso (rate limiting) é restringir quantas chamadas um cliente pode fazer em um intervalo. Protege a API de picos, de erros de programação do cliente e de abusos.Ir para a seção
  5. Idempotência e erros: repetir a chamada sem duplicar o efeitoUma operação idempotente produz o mesmo efeito quando executada uma vez ou várias. Em redes instáveis, isso permite repetir chamadas sem medo de cobrar duas vezes ou criar pedidos duplicad…Ir para a seção
  6. Medir, testar e evoluir a API sem quebrar quem a usaUma API de alto desempenho não termina no projeto. Ela precisa de medição contínua, teste antes dos picos e um modo de mudar sem derrubar integrações que dependem dela.Ir para a seção

Imagine um aplicativo de pedidos que funcionava bem com 200 itens no catálogo. Meses depois, o catálogo cresce, a tela inicial passa a pedir tudo de uma vez e cada abertura demora o suficiente para o usuário desistir. Ninguém mexeu em servidor, banco ou rede. O que mudou foi o volume, e a API REST foi desenhada como se ele nunca fosse mudar.

Na Trilion, que desenvolve sistemas desde 1995, vemos esse padrão com frequência: a lentidão de uma API REST quase sempre nasce no projeto dela, não na máquina que a hospeda. Neste artigo, você vai entender o que é uma API REST, como projetar paginação, cache, limites de uso e repetição segura de chamadas, e como medir o resultado sem adivinhar.

Se você prefere conversar sobre o seu caso com quem projeta esse tipo de sistema, a página de aplicações de alta performance mostra como trabalhamos, e o briefing leva poucos minutos.

API REST: o que é e por que o projeto define o desempenho

Uma API REST é uma interface em que sistemas conversam por HTTP, tratando cada coisa (pedido, cliente, produto) como um recurso com endereço próprio. O desempenho depende de como esses recursos são desenhados.

O que é uma API REST

Uma API é a porta pela qual um programa pede dados ou ações a outro. REST é um estilo de projeto para essa porta, definido pelo cientista da computação Roy Fielding na tese de doutorado de 2000, segundo a Wikipédia. Na prática, cada recurso tem um endereço, e verbos como GET, POST, PUT e DELETE dizem o que fazer com ele.

As restrições que ajudam a escalar

Fielding descreveu restrições que explicam por que o estilo escala bem. A mais importante para desempenho é a ausência de estado no servidor: cada requisição traz tudo o que o servidor precisa, sem depender de memória de conversas anteriores. Outra é a possibilidade de cache, pois a resposta declara se pode ser reaproveitada. Há ainda a separação entre cliente e servidor e o sistema em camadas, em que o cliente não sabe se fala com o servidor final ou com um intermediário.

Sem estado, qualquer servidor de um grupo atende qualquer chamada. Isso permite somar máquinas quando o volume cresce, sem que o usuário perceba.

Onde o desempenho se decide

Uma API rápida tem poucas respostas desnecessárias. Quatro decisões de projeto pesam mais do que qualquer ajuste de servidor:

  • Tamanho da resposta: entregar só o que o cliente precisa, em lotes controlados.
  • Reaproveitamento: permitir que navegadores, aplicativos e intermediários guardem respostas que não mudaram.
  • Proteção: limitar o uso para que um cliente não prejudique os demais.
  • Repetição segura: aceitar que a mesma chamada chegue 2 vezes sem duplicar o efeito.

Quando o problema não está na API

Nem toda lentidão vem do desenho da interface. Uma resposta pode demorar porque a consulta ao banco é pesada ou porque a tarefa deveria rodar em segundo plano. Antes de reescrever endpoints, vale separar as causas. Nossos artigos sobre banco de dados lento e sobre observabilidade ajudam a apontar onde o tempo se perde.

Antes de otimizar uma API REST, descubra onde o tempo é gasto. Compartilhe este artigo com quem cuida da sua plataforma e comparem o que cada um observa.

Paginação, filtros e campos: entregar só o necessário

Paginar é devolver uma lista em partes, com um ponto de continuação, em vez de despejar todos os registros. É a primeira defesa de uma API REST contra o crescimento dos dados.

Por que listar tudo de uma vez não escala

Uma lista sem limite funciona enquanto os dados são poucos. Quando crescem, a resposta fica pesada, o banco trabalha mais, a rede transfere mais e o aplicativo do usuário consome memória para exibir o que ele nem vai ver. O custo cresce junto com os dados, e o pior momento costuma ser justamente o de maior movimento.

Paginação por cursor: o exemplo de uma API conhecida

A documentação da Stripe descreve um modelo de paginação por cursor. A lista aceita um parâmetro de limite, que vai de 1 a 100 itens e tem padrão de 10, e um identificador de referência: com ele, o cliente pede os itens depois ou antes de um objeto já conhecido. A resposta traz também um indicador dizendo se há mais itens.

Como o ponto de continuação é um objeto e não um número de página, a lista não se desloca quando novos registros entram no meio da leitura. Esse é o ganho do cursor sobre a paginação por número de página.

Decida a paginação no primeiro dia

O guia de projeto de APIs do Google (a proposta AIP-158) orienta que as chamadas que devolvem coleções tenham paginação desde o início, porque acrescentá-la depois é uma mudança que quebra os clientes existentes. O guia também diz que o servidor deve definir e documentar um tamanho padrão, reduzir pedidos acima do máximo ao máximo permitido, e tratar o token de continuação como texto opaco, que o cliente não deve interpretar.

O ponto prático é simples: toda lista pública nasce paginada, mesmo que hoje tenha 20 itens.

Filtros e seleção de campos

Além de dividir a lista, permita que o cliente peça só o que interessa. Um filtro por status, período ou responsável evita que o aplicativo baixe tudo e filtre depois. A seleção de campos evita enviar 40 atributos quando a tela usa 5. Cada filtro aceito precisa de um índice correspondente no banco; do contrário, a flexibilidade da API vira consulta lenta, tema que tratamos no artigo sobre índices, consultas e modelagem.

Checklist rápido para listas:

  • Limite padrão: definido, documentado e com teto máximo.
  • Cursor: o ponto de continuação vem na resposta, e o cliente não precisa montá-lo.
  • Ordenação estável: a mesma ordem em todas as páginas, com critério de desempate.
  • Filtros úteis: só os que o banco consegue atender com índice.
  • Campos sob medida: a opção de pedir menos dados por chamada.
Imagem ilustrativa: indústria 5.0

Cache HTTP e compressão: não refazer o trabalho

O cache HTTP permite que navegadores e intermediários reutilizem respostas já recebidas, e a compressão reduz o tamanho do que trafega. Os dois cortam trabalho do servidor sem mudar a regra de negócio.

Cache-Control: quanto tempo uma resposta vale

Segundo a documentação da Mozilla (MDN), o cabeçalho Cache-Control comanda o comportamento de cache. Com max-age, a resposta é considerada fresca por um número de segundos. Com no-cache, ela pode ser guardada, mas precisa ser revalidada antes de cada reuso. Com private, só o navegador do usuário a guarda, o que protege respostas personalizadas. Já o no-store impede qualquer armazenamento, e a própria MDN avisa que ele é usado em excesso.

Nos dados que mudam pouco, como categorias ou tabelas de apoio, um tempo de validade curto já tira muita carga do servidor.

ETag e resposta 304: perguntar antes de baixar

Quando uma resposta vence, o cliente não precisa baixar tudo de novo. Ele envia o identificador (ETag) da versão que possui, e o servidor responde com o código 304, Not Modified, sem corpo, se nada mudou. Se mudou, devolve a versão nova com o código 200. A MDN descreve esse mecanismo como validação por requisição condicional.

O ganho é duplo: o servidor não monta a resposta inteira e a rede não carrega dados repetidos. Em APIs com muitas leituras, isso pesa.

Compressão: gzip e Brotli

A MDN explica que o cliente informa os algoritmos aceitos no cabeçalho Accept-Encoding, e o servidor comprime o corpo da resposta e indica a escolha em Content-Encoding. Gzip é o mais comum, e Brotli (br) é o desafiante mais novo. O servidor deve enviar também o cabeçalho Vary: Accept-Encoding, para que intermediários guardem cada versão separadamente.

Respostas em JSON são texto e se beneficiam bastante. Arquivos já comprimidos, como imagens e vídeos, não devem ser comprimidos de novo.

O cuidado com dados pessoais e atuais

Cache vale para o que pode ser reaproveitado. Saldo, estoque em tempo real e dados de um usuário específico pedem cuidado: use a marcação private ou a revalidação, e nunca deixe uma resposta personalizada em cache compartilhado. Em muitos casos, a solução é combinar o cache HTTP com uma camada de dados, como mostramos em Redis e cache.

Qual endpoint da sua API recebe a mesma pergunta o dia inteiro e devolve sempre a mesma resposta? Comece por ele e conte nos comentários o que encontrou.

Limites de uso: proteger a API sem punir quem a usa bem

Limitar a taxa de uso (rate limiting) é restringir quantas chamadas um cliente pode fazer em um intervalo. Protege a API de picos, de erros de programação do cliente e de abusos.

O código 429 e o cabeçalho Retry-After

A MDN define o código de resposta 429, Too Many Requests, como o aviso de que o cliente enviou pedidos demais em um dado intervalo. A resposta pode trazer o cabeçalho Retry-After, que informa quanto tempo o cliente deve esperar antes de tentar de novo. Os limites costumam se basear no endereço IP ou, quando há autenticação, no usuário ou no aplicativo autorizado.

Comunicar o limite antes de ele estourar

A documentação da API REST do GitHub mostra um bom exemplo de transparência. Cada resposta traz cabeçalhos com o limite total, as chamadas restantes e o instante em que a janela reinicia. Ao exceder o limite, a plataforma responde com 403 ou 429 e orienta o cliente a não tentar de novo antes do horário informado; em limites secundários, recomenda esperar o tempo indicado e aumentar a espera de forma exponencial se as falhas continuarem.

O princípio vale para qualquer API: o cliente que sabe quanto ainda pode usar se comporta melhor do que o que descobre o limite pelo erro.

Como escolher os limites

Não existe número universal. Os limites partem do uso legítimo: quantas chamadas um aplicativo bem escrito faz por minuto, quais rotinas em lote existem e quais parceiros precisam de capacidade maior. Vale diferenciar rotas leves de rotas caras, como relatórios e buscas, que merecem limites mais apertados.

  1. Meça o uso atual por cliente e por rota.
  2. Defina limites acima do uso legítimo e abaixo do que derruba o sistema.
  3. Devolva 429 com Retry-After e cabeçalhos que informem o saldo.
  4. Registre quem bate no limite com frequência e converse com essa pessoa.
  5. Revise os limites quando o volume ou as integrações mudarem.

Limite não substitui fila

Quando uma operação é pesada, recusar o excesso não resolve o problema de fundo. Relatórios longos, importações e envios em massa devem sair da requisição e ir para segundo plano, com a API respondendo que o pedido foi aceito. Esse desenho está no artigo sobre filas e processamento assíncrono.

Imagem ilustrativa: computação e IA

Idempotência e erros: repetir a chamada sem duplicar o efeito

Uma operação idempotente produz o mesmo efeito quando executada uma vez ou várias. Em redes instáveis, isso permite repetir chamadas sem medo de cobrar duas vezes ou criar pedidos duplicados.

O que a especificação do HTTP diz

Segundo a MDN, um método HTTP é idempotente quando o efeito pretendido no servidor de uma única requisição é igual ao de várias requisições idênticas. GET, PUT e DELETE são idempotentes. POST e PATCH não têm essa garantia. As respostas podem diferir: o primeiro DELETE pode devolver 200 e os seguintes, 404, e ainda assim o efeito pretendido é o mesmo.

O problema do POST repetido

Imagine que o aplicativo envia um pedido, a rede cai antes da resposta e o aplicativo tenta de novo. Se o servidor não souber que se trata da mesma intenção, cria 2 pedidos. A solução usual é o cliente enviar uma chave única de operação em cada tentativa, e o servidor guardar o resultado ligado a essa chave. Na segunda chegada, devolve o resultado já gravado.

Erros que ajudam o cliente a agir

Uma API de alto desempenho também falha bem. Os códigos de status precisam distinguir o que o cliente pode corrigir (série 4xx) do que é problema do servidor (série 5xx). A mensagem deve dizer o que aconteceu em linguagem objetiva, e a resposta deve indicar se vale tentar de novo. Sem isso, o aplicativo repete chamadas que nunca vão funcionar e aumenta a carga justamente quando o sistema está em dificuldade.

Tempo limite e repetição com espera

Todo cliente deve ter um tempo limite e repetir com espera crescente, para não formar uma avalanche de tentativas simultâneas. Do lado do servidor, defina quanto tempo uma requisição pode durar. Quando uma chamada passa disso, ela deve responder que aceitou o trabalho e entregar o resultado depois.

  • Chave de idempotência: enviada pelo cliente em operações que criam ou cobram algo.
  • Códigos de status corretos: 4xx para erro do cliente, 5xx para falha do servidor.
  • Tempo limite: definido nos dois lados da conversa.
  • Espera crescente: intervalo maior a cada nova tentativa.

Medir, testar e evoluir a API sem quebrar quem a usa

Uma API de alto desempenho não termina no projeto. Ela precisa de medição contínua, teste antes dos picos e um modo de mudar sem derrubar integrações que dependem dela.

O que medir em cada endpoint

Medir só a média esconde o problema. O que incomoda o usuário é a minoria de chamadas muito lentas, por isso acompanhe os tempos das chamadas mais demoradas, a taxa de erros e o volume por rota. Registre também o tamanho das respostas e o tempo gasto no banco. Com esses dados, a conversa deixa de ser opinião.

Teste antes do pico

Descobrir o limite da API em um dia de campanha é caro. O teste de carga reproduz o uso esperado, e um pouco acima dele, em ambiente controlado, e mostra em que ponto o sistema começa a engasgar. Abordamos o método no artigo sobre teste de carga e de performance.

Versionar sem quebrar integrações

Quando a API é usada por aplicativos, parceiros e outros sistemas, mudar um campo pode parar uma operação inteira. Por isso, mudanças que quebram compatibilidade entram em uma nova versão, e a antiga convive por um prazo combinado. Acrescentar campos opcionais costuma ser seguro; remover ou renomear, não. Quem integra sistemas conhece bem esse cuidado, e a frente de integração de sistemas trata do assunto com mais detalhe.

Passo a passo para revisar uma API existente

  1. Liste os endpoints e meça tempo, volume e tamanho de resposta de cada um.
  2. Marque as listas sem paginação e as respostas que enviam campos que ninguém usa.
  3. Veja quais respostas podem ganhar cache, validação por ETag e compressão.
  4. Defina limites de uso e o formato das respostas de erro.
  5. Reveja as operações que criam ou cobram algo e acrescente idempotência.
  6. Repita a medição e compare com a primeira, em vez de confiar na impressão.

Uma API só é rápida quando os números dizem isso. Peça a medição antes de aprovar qualquer mudança.

Conclusão

Uma API REST de alto desempenho nasce de decisões de projeto: listas paginadas, respostas enxutas, cache e compressão bem aplicados, limites claros, chamadas repetíveis com segurança e medição constante. Servidor maior ajuda, mas não corrige um desenho que cresce junto com os dados.

Vimos que a ausência de estado permite somar servidores, que a paginação deve existir desde o primeiro dia, que o cache e o código 304 poupam trabalho, que o código 429 e o cabeçalho Retry-After organizam o excesso e que a chave de idempotência evita duplicidade. Nada disso exige promessa de ganho: exige método, medição e disciplina.

Se a sua API já mostra sinais de cansaço, monte o briefing na página de aplicações de alta performance ou pelo formulário de orçamento. A proposta é escrita depois do briefing, e o valor depende de escopo, integrações, volume e prazo.

Sobre este texto

Este artigo foi escrito pela equipe da Trilion a partir da prática de projeto de sistemas e da leitura da documentação pública das plataformas citadas. Os fatos sobre HTTP, paginação e limites de uso foram conferidos nas páginas listadas abaixo em 07/11/2026. Nomes de empresas aparecem apenas como exemplos factuais, sem indicação ou comparação. O texto não promete ganho de desempenho em números, porque ele depende do sistema, do volume e da infraestrutura de cada empresa.

Perguntas frequentes

O que é uma API REST?

É uma interface em que sistemas trocam dados por HTTP, tratando cada item (pedido, cliente, produto) como um recurso com endereço próprio. O estilo REST foi descrito por Roy Fielding na tese de doutorado de 2000 e inclui restrições como ausência de estado no servidor e possibilidade de cache.

Por que paginar uma API?

Porque listas sem limite ficam pesadas quando os dados crescem, sobrecarregando banco, rede e aplicativo. Paginar devolve a lista em partes, com um ponto de continuação. Segundo o guia de APIs do Google, incluir paginação depois do lançamento quebra os clientes existentes, então ela deve existir desde o início.

Para que serve o código 429?

O código 429, Too Many Requests, avisa que o cliente enviou chamadas demais em um intervalo. A resposta pode trazer o cabeçalho Retry-After, com o tempo de espera antes de tentar de novo. Ele permite proteger a API de picos e abusos sem derrubar o serviço para todos.

O que significa uma operação idempotente?

É a que produz o mesmo efeito quando executada uma vez ou várias. Em HTTP, GET, PUT e DELETE são idempotentes; POST e PATCH não têm essa garantia. Para operações como criar pedidos ou cobrar, usa-se uma chave única enviada pelo cliente, que evita duplicidade em novas tentativas.

Cache HTTP serve para dados que mudam o tempo todo?

Serve com cuidado. Para dados que mudam pouco, um tempo de validade curto já alivia o servidor. Para dados atuais ou personalizados, usa-se revalidação com ETag, que devolve 304 quando nada mudou, e a marcação private, que impede o armazenamento em cache compartilhado.

Método

Como a Trilion conduz um projeto de alta performance

Do briefing à operação, em 5 etapas e com tudo por escrito. A proposta vem depois do briefing e o valor depende de escopo, integrações, volume e prazo.

  1. Briefing em 3 passos

    Você conta o que precisa construir; nós devolvemos perguntas e um caminho possível.

  2. Desenho por escrito

    Diagnóstico dos gargalos, metas de desempenho, arquitetura e plano de testes, antes de qualquer alteração.

  3. Construção em fatias

    Mudanças pequenas e medidas, com comparação antes e depois em cada fatia.

  4. Testes e homologação

    Casos do dia a dia da sua operação, com plano de retorno antes de publicar.

  5. Operação e evolução

    Acompanhamento combinado na proposta e ajustes guiados por indicadores.

Vamos deixar o seu sistema à altura da sua operação

Conte o que precisa resolver. A Trilion responde com uma proposta escrita, depois do briefing, e leva o projeto do código à operação.

Falar no WhatsApp
Blog da Trilion · Inteligência artificial

Continue aprendendo sobre IA

Artigos do blog da Trilion que aprofundam os temas deste texto. Arraste, use as setas ou o teclado.

WhatsApp
WhatsApp

Converse com a Trilion

Diga-nos o seu nome, e a conversa abre em seguida