Neste artigo
- O que é um recurso e por que ele é a base do design
- Métodos HTTP: as operações da API
- Status code: falar a língua do cliente
- JSON e o contrato entre as partes
- Autenticação e segurança básica de API
- Versionamento e evolução sem quebrar consumidores
- Erros de design que nascem com a API
- Como o design de API encaixa na carreira
- REST e API são a mesma coisa?
- Qual a diferença entre PUT e PATCH?
- Por que não devolver sempre 200?
- Como versionar uma API sem quebrar os clientes?
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étodo | Operação | Exemplo |
|---|---|---|
| GET | Ler | GET /usuarios |
| POST | Criar | POST /usuarios |
| PUT / PATCH | Atualizar | PUT /usuarios/1 |
| DELETE | Remover | DELETE /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.