Busque em todas as páginas da documentação
Uma API é um contrato: uma promessa sobre quais requisições um serviço aceitará e quais formatos de resposta ele retornará, feita a chamadores que não podem ver - e não deveriam precisar ver - nada sobre a implementação por trás dela. Projetar uma API bem significa projetar essa promessa deliberadamente, antes do código, em vez de deixá-la emergir como qualquer formato que um manipulador de rota produziu.
Esta página é o modelo mental por trás do restante da seção. Fundamentos de Design de API mostra os padrões de trabalho - URLs de recursos, envelopes JSON, códigos de status - e Padrões de Resposta de Erro, Paginação e Filtragem, Versionamento e Descontinuação e OpenAPI e Swagger aprofundam partes específicas desse contrato. Aqui, o objetivo é entender o que torna um contrato bom, e não apenas um endpoint funcional.
A palavra "design" em design de API está fazendo um trabalho real: um recurso é o substantivo que uma API expõe - um pedido, um cliente, uma fatura - e os métodos HTTP (GET, POST, PATCH, DELETE) são os verbos aplicados a ele.
Essa forma orientada a recursos não é uma escolha estética; é o que permite que um chamador que nunca leu seu código-fonte adivinhe corretamente que DELETE /orders/:id remove um pedido, sem uma linha de documentação.
Uma alternativa estilo RPC - POST /deleteOrder - também funciona, mas força que cada ação seja aprendida individualmente, pois a URL não carrega mais nenhum significado por si só.
Uma analogia útil: uma API bem projetada é uma máquina de vendas, não uma conversa.
Um chamador não precisa explicar o que quer em texto corrido ou adivinhar o estado interno - ele aperta um botão bem rotulado (uma URL de recurso mais um método) e obtém um resultado previsível e documentado a cada vez, independentemente do que está acontecendo dentro da máquina.
GET /v1/orders/:id # buscar um pedido
POST /v1/orders # criar um pedido
PATCH /v1/orders/:id # atualizar parcialmente um pedido
DELETE /v1/orders/:id # remover um pedidoIdempotência é a propriedade de que chamar uma operação duas vezes tem o mesmo efeito que chamá-la uma vez - PUT e DELETE devem ser idempotentes pelos próprios semânticos do HTTP, enquanto POST geralmente não é, e é por isso que endpoints de pagamento frequentemente adicionam um cabeçalho explícito Idempotency-Key para obter essa garantia onde o método HTTP sozinho não a fornece.
Uma vez que uma API é lançada e um chamador escreve código contra ela, o formato da resposta se torna uma infraestrutura de suporte sobre a qual o proprietário da API não tem mais controle total - um aplicativo móvel no bolso de um usuário, ou a integração de um parceiro, continua chamando o formato antigo até que alguém atualize esse código, o que a equipe da API não pode forçar ou sequer ver acontecer.
Esta é a tensão central no design de API: internamente, refatorar é barato porque cada chamador é um colega de trabalho que pode atualizar na mesma pull request; externamente, um "refatoramento" de um formato de resposta é uma mudança disruptiva que é lançada em seu próprio cronograma, invisível para a equipe que a fez até que os tickets de suporte cheguem.
Códigos de status carregam significado independente do corpo da resposta, o que os torna úteis para ramificação programática antes que um cliente sequer analise o JSON.
// O código de status é a primeira coisa em que um cliente ramifica - antes da análise do corpo
if (response.status === 404) {
// o chamador pode reagir a "não encontrado" sem ler response.body
} else if (response.status >= 500) {
// seguro para tentar novamente; 4xx geralmente não é
}Essa distinção 4xx versus 5xx é um mecanismo, não uma convenção: clientes HTTP, proxies e bibliotecas de retentativa tratam os dois intervalos de forma diferente por padrão (5xx geralmente é retentado automaticamente; 4xx geralmente não é), então retornar 500 para um erro de validação diz à infraestrutura intermediária para retentar uma requisição que falhará identicamente todas as vezes.
Um envelope consistente - envolvendo payloads de sucesso em { data: ... } e erros em { error: ... } - existe por uma razão relacionada: permite que um cliente escreva uma única lógica de tratamento de resposta para cada endpoint da API, em vez de um caso especial por rota. Sem essa consistência, cada novo endpoint é um pequeno projeto de integração para cada consumidor, pois nada sobre os dezenove endpoints anteriores prevê o formato do vigésimo.
A estabilidade do contrato tem um custo real, e entender esse custo é o que separa o design deliberado de API da supercautela ou da imprudência. Um campo que não é realmente utilizado por nenhum chamador pode ser removido livremente; um campo do qual uma integração depende silenciosamente não pode, mesmo que pareça não utilizado de dentro da base de código - é por isso que APIs de produção cada vez mais instrumentam o uso da resposta (quais campos os clientes realmente leem) antes de remover qualquer coisa.
Versionamento existe para permitir que um contrato evolua sem quebrar chamadores existentes: uma nova versão principal (/v2/orders) pode alterar os formatos de resposta livremente, enquanto /v1 continua servindo exatamente o que sempre serviu até ser formalmente descontinuado em um cronograma publicado. A alternativa - mutar /v1 no local - troca um esquema de URL limpo por um contrato imprevisível, o que é uma troca pior para qualquer API com chamadores fora do controle direto da equipe.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| REST, orientado a recursos | Previsível, cacheável, amplamente com ferramentas (OpenAPI, clientes gerados) | Verboso para ações puras que não são realmente CRUD | APIs públicas e B2B, domínios com muitas operações CRUD |
Estilo RPC (/doThing) | Simples para adicionar ações únicas | Sem vocabulário compartilhado entre endpoints; mais difícil de documentar genericamente | Endpoints internos com muitas ações, operações estilo comando |
| GraphQL | Clientes buscam exatamente os campos de que precisam; endpoint único | Caching e limitação de taxa são mais difíceis; configuração do lado do servidor mais complexa | UIs ricas em dados com muitas formas de cliente a partir de um backend |
O tratamento de erros merece a mesma disciplina de contrato que as respostas de sucesso, e muitas vezes recebe menos na prática. Um campo code estável e legível por máquina (ORDER_NOT_FOUND) permite que os clientes ramifiquem por significado; uma string message legível por humanos não, pois essa string pode mudar com uma edição de cópia e quebrar silenciosamente qualquer cliente que estivesse correspondendo ao padrão em seu texto exato. Padrões de Resposta de Erro cobre o formato Problem Details RFC 9457 que esta stack padroniza, mas o princípio subjacente se aplica independentemente do formato: qualquer coisa que o cliente deva ramificar programaticamente tem que ser tão estável quanto o próprio contrato.
Ferramentas modernas mudaram parte dessa disciplina de convenção para aplicação. Uma especificação OpenAPI, gerada a partir de código ou escrita à mão e validada em CI, transforma "o contrato é o que a documentação diz" em "o contrato é o que uma máquina pode verificar uma resposta contra" - capturando desvios entre documentação e implementação antes que um chamador perceba a incompatibilidade.
POST /orders/:id/cancel trata "cancelar" como uma ação em um recurso em vez de abandonar completamente o design orientado a recursos.Chamadores externos à equipe - aplicativos móveis, integrações de parceiros, outros serviços - escrevem código com base nos formatos de resposta e códigos de status exatos que uma API retorna, e não podem ver ou influenciar como essa resposta foi produzida internamente.
Ele dá a cada endpoint um vocabulário compartilhado e adivinhável - um chamador que entende GET /orders/:id pode prever corretamente o que GET /customers/:id faz, sem documentação, porque o padrão se repete.
Clientes HTTP, proxies e bibliotecas de retentativa ramificam com base no intervalo do código de status antes mesmo de analisar o corpo da resposta - muitos retentam automaticamente respostas 5xx e não retentam respostas 4xx, então o código que você retorna determina o comportamento real da infraestrutura, não apenas a semântica.
Ele permite que um cliente escreva um código compartilhado para verificar data versus error em todos os endpoints, em vez de escrever lógica de análise personalizada por rota, porque o formato de cada endpoint é ligeiramente diferente.
Geralmente apenas ao adicionar um novo campo opcional que nenhum cliente existente lê ainda - remover um campo, renomear um ou alterar o tipo ou significado de um campo é uma mudança disruptiva, independentemente de quão pequena pareça na diferença.
O texto da mensagem é para humanos e pode mudar com uma edição de cópia a qualquer momento; um campo code estável e legível por máquina é a parte do contrato que deve ser dependida programaticamente.
Não - REST se encaixa bem em cenários com muitas operações CRUD, cacheáveis e amplamente com ferramentas, enquanto GraphQL se encaixa em UIs ricas em dados que precisam de muitas combinações de campos diferentes de um único backend; a escolha depende da diversidade de formas do chamador e das necessidades de caching, não de um ser universalmente melhor.
Cada inconsistência (um formato de envelope diferente, um código de status imprevisível) se torna trabalho de integração que cada chamador tem que refazer por endpoint, e cada mudança disruptiva "pequena" se torna um incidente de suporte para quem dependia do formato antigo.
POST não é idempotente pelos próprios semânticos do HTTP, então uma requisição retentada (de uma rede instável, por exemplo) pode criar um recurso duplicado, a menos que a API adicione um mecanismo explícito, como um cabeçalho Idempotency-Key, para tornar as retentativas seguras.
Ele transforma o contrato de uma descrição em um documento para um esquema verificável por máquina - uma resposta validada pela especificação ou corresponde ao que foi prometido ou falha em uma verificação, capturando desvios entre documentação e comportamento real automaticamente.
Mesmo equipes disciplinadas eventualmente precisam de uma mudança que genuinamente não possa permanecer retroativamente compatível - o versionamento é o que dá aos chamadores existentes um alvo estável (/v1) para continuar usando enquanto novos chamadores adotam o novo formato (/v2), em vez de forçar todos a uma mudança disruptiva de uma vez.
Versões da Stack: Esta página é conceitual e não está vinculada a uma versão específica da stack.
Revisado por Chris St. John·Última atualização: 15 de jul. de 2026