<\> Casa do Dev
Notícias abrir
Ferramentas abrir
Vagas abrir
Aprender abrir
Comunidade abrir
Guia de Compras abrir

API REST: fundamentos que todo backend precisa entender

DA

7 min

API REST: fundamentos que todo backend precisa entender

Entenda os fundamentos de API REST: recursos, métodos HTTP, status codes e JSON, com os erros de design que você deve evitar.

Neste artigo

Toda aplicação moderna conversa por uma interface, e a forma mais comum de interface é a API REST. É ela que liga o aplicativo ao servidor, o frontend ao banco e o seu serviço ao serviço de outro time. Entender recurso, método e status code deixa de ser opcional quando você mexe com integração, e este guia explica esses fundamentos sem o jargão que costuma confundir.

Uma API REST expõe recursos, cada um numa URL, e usa os métodos HTTP para definir a operação: GET lê, POST cria, PUT ou PATCH atualiza e DELETE remove. A resposta volta em JSON, com um status code que informa o resultado. A base conceitual está bem explicada no guia de fundamentos de API.

O que é um recurso e por que ele é a base do design

Recurso é o substantivo da sua API: o que ela manipula, como usuário, pedido ou produto. Cada recurso tem uma URL que o identifica, e as operações acontecem sobre ele. O erro de design mais comum é nomear a URL pela ação, como /criar-usuario, em vez de pelo recurso /usuarios com o método certo.

💡 Dica: URL nomeia o recurso, método nomeia a ação. POST /usuarios lê "criar usuário" sem poluir a URL de verbo. Quem mantém a regra simples não cria uma API que cada rota vira uma exceção.

Métodos HTTP: as operações da API

Cada método expressa uma intenção. A maioria das APIs usa quatro, e a troca entre eles é a fonte de bugs sutis.

MétodoOperaçãoExemplo
GETLerGET /usuarios
POSTCriarPOST /usuarios
PUT / PATCHAtualizarPUT /usuarios/1
DELETERemoverDELETE /usuarios/1

GET não deve ter efeito colateral; POST cria; a diferença entre PUT e PATCH é que o primeiro substitui o recurso inteiro e o segundo altera parcial. Usar GET para criar ou POST para tudo não é só gosto: quebra a previsibilidade e entra em conflito com ferramentas e caches.

Status code: falar a língua do cliente

O status code da resposta informa o cliente o que aconteceu, e é errado devolver sempre 200. As famílias mais usadas são 2xx para sucesso, 4xx para erro do cliente e 5xx para erro do servidor. Distingui-los é o que permite ao frontend reagir certo em vez de adivinhar.

  • 200 OK: leitura e atualização concluídas.
  • 201 Created: recurso criado.
  • 400 Bad Request: entrada inválida do cliente.
  • 404 Not Found: recurso não existe.
  • 500 Internal Server Error: falha do servidor.

ℹ️ Info: status code certo vale ouro em integração, porque a outra ponta decide o que fazer com base nele. Um 500 mascarado de 200 faz o cliente processar erro como sucesso e esconder a falha.

JSON e o contrato entre as partes

JSON é o formato que a resposta carrega. A chave do design é manter o contrato estável: mesmos campos, mesmos tipos, para o cliente não quebrar a cada deploy. Documentar esse contrato e versionar mudanças evita o cenário em que a API evolui e o consumidor descobre o erro em produção.

{
  "id": 1,
  "nome": "Maria",
  "ativo": true
}

No coração de uma API bem feita está o respeito pelo contrato. Não renomeie campo sem aviso, não mude tipo de número para texto sem versionar. É disciplina de integração, e quem não tem destrói a confiança de quem consome a API.

Autenticação e segurança básica de API

Uma API que mexe em dado de usuário precisa saber quem está chamando. O padrão comum é um token enviado no cabeçalho da requisição, que o servidor valida para autorizar a ação. Sem isso, qualquer um que descobrir a URL teria acesso, o que transforma a API em porta aberta.

GET /usuarios/1 HTTP/1.1
Authorization: Bearer TOKEN_AQUI

Três regras de base cobrem a maioria dos vazamentos: trate toda entrada como não confiável, exija autenticação nas operações que alteram dado e não exponha chave nem senha na URL ou no log. Segurança de API é disciplina de dois lados: a sua e a de quem a consome.

⚠️ Atenção: nunca trafegue credencial na URL, porque a URL vaza em log, histórico e cache. Token vai no cabeçalho de autorização, onde não aparece em logs padrão.

Versionamento e evolução sem quebrar consumidores

API muda, e a arte está em mudar sem derrubar quem já usa. Para mudança compatível, adicione campo novo sem remover o velho. Para quebra, crie uma versão nova e dê tempo para migração. O consumidor que confia no seu contrato é o seu produto, não um detalhe.

Documentação vive junto do código, e a versão é parte do contrato. Quando a evolução é pensada desde o início, a API envelhece bem: novas features entram sem reinventar o que já funciona e sem gerar um êxodo de clientes a cada deploy.

Erros de design que nascem com a API

Os problemas de API costumam nascer no primeiro desenho, e três são recorrentes. O primeiro é URL que conta história por verbo, como /deletar-usuario, quando deveria ser recurso com método. O segundo é resposta sem status consistente, que força o cliente a adivinhar. O terceiro é contrato instável, que quebra consumidor a cada mudança.

Esses erros se evitam com uma regra simples: recurso na URL, ação no método, status honesto e contrato documentado. Não é exigência de guru, é o que mantém uma API consumível anos depois de quem a escreveu ter saído. O custo de corrigir um design mal nascido é sempre maior que o de acertar na origem.

Como o design de API encaixa na carreira

Saber desenhar API é o fio que liga backend, frontend e integração, e aparece em toda entrevista de pleno. O conceito de recurso, método e status transcende a linguagem: vale em Node, Python ou Java. Para construir uma de verdade com Python, o bootcamp de backend Python com FastAPI é o caminho prático, e para quem quer entender a escolha de runtime, o guia de Node, Deno e Bun ajuda a decidir onde rodar.

Perguntas frequentes

REST e API são a mesma coisa?

Não. API é o contrato de comunicação, o genérico; REST é um estilo de arquitetura que organiza a API em recursos e usa os métodos HTTP. Nem toda API é REST, mas REST é o estilo dominante.

Qual a diferença entre PUT e PATCH?

PUT substitui o recurso inteiro; PATCH altera só os campos enviados. Na prática, PATCH é mais comum em atualização parcial, e a escolha deve refletir como a sua API trata o que não foi enviado.

Por que não devolver sempre 200?

Porque o status é informação. Se o cliente trata erro como sucesso, ele segue o fluxo com dado errado. Distinguir 2xx, 4xx e 5xx faz a integração reagir e debugar de forma correta.

Como versionar uma API sem quebrar os clientes?

Mantenha o contrato estável e, quando precisar mudar de forma incompatível, crie uma versão nova em vez de alterar a existente. Mudança compatível pode entrar em evolução gradual; quebra exige nova versão.

Produtos relacionados

Este conteúdo tem links de afiliado: se você comprar por eles, podemos receber uma comissão sem custo extra para você. A escolha dos produtos segue critérios próprios e não é influenciada por comissão.

O que você achou deste artigo?

Responda a Pergunta do Dia Teste seu conhecimento e mantenha sua streak. Crie seu Dev Card público Perfil dev compartilhável em um único link.

Depois dessa formação...

Veja vagas em tecnologia →

Vagas relacionadas

Ver todas as vagas →
DA

Escrito por

Dagmar

Atualizado em 06/10/2026 •

Ver perfil do autor

COMPARTILHAR