HTTP para APIs: métodos e status
Métodos, idempotência e códigos de status para desenhar e depurar uma API sem surpresas.
8 min de leitura · Iniciante · Revisado em
Uma requisição e sua resposta
Toda conversa HTTP tem duas partes. A requisição diz o que o cliente quer: método, caminho, cabeçalhos e, às vezes, um corpo. A resposta diz o que aconteceu: um código de status, cabeçalhos e, quase sempre, um corpo.
Criar uma anotação
POST /trilhas/42/anotacoes HTTP/1.1
Host: api.trilha.info
Content-Type: application/json
Authorization: Bearer eyJhbGciOi...
{ "texto": "Revisar flexbox" }HTTP/1.1 201 Created
Location: /trilhas/42/anotacoes/7
Content-Type: application/json
{ "id": 7, "texto": "Revisar flexbox" }Métodos: o verbo da requisição
| Método | Uso | Seguro | Idempotente |
|---|---|---|---|
GET | Ler um recurso ou uma lista | Sim | Sim |
POST | Criar um recurso ou disparar uma ação | Não | Não |
PUT | Substituir um recurso inteiro | Não | Sim |
PATCH | Alterar parte de um recurso | Não | Não garantido |
DELETE | Remover um recurso | Não | Sim |
- Seguro
- Não altera nada no servidor. Pode ser repetido, guardado em cache e pré-carregado à vontade.
- Idempotente
- Repetir a mesma requisição deixa o servidor no mesmo estado que uma única chamada. Apagar algo duas vezes continua com o recurso apagado.
Status: o que aconteceu
2xx
Deu certo
A requisição foi entendida e atendida.
3xx
Vá para outro lugar
O recurso mudou de endereço ou não mudou desde a última vez.
4xx
Erro do cliente
Algo na requisição está errado. Repetir igual não resolve.
5xx
Erro do servidor
A requisição parecia válida, mas o servidor falhou.
1xx
Informativo
Respostas provisórias, raras no dia a dia de uma API.
| Código | Nome | Quando usar |
|---|---|---|
200 | OK | Leitura ou alteração bem-sucedida, com corpo. |
201 | Created | Recurso criado. Envie Location com o endereço dele. |
204 | No Content | Deu certo e não há o que devolver, como em um DELETE. |
304 | Not Modified | O cliente pode usar a cópia que já tem em cache. |
400 | Bad Request | Corpo ou parâmetros malformados. |
401 | Unauthorized | Falta autenticação, ou ela é inválida. |
403 | Forbidden | Autenticado, mas sem permissão. |
404 | Not Found | O recurso não existe, ou você não deve saber que existe. |
409 | Conflict | Conflita com o estado atual, como um e-mail já cadastrado. |
422 | Unprocessable Content | Formato correto, mas a validação falhou. |
429 | Too Many Requests | Limite de requisições atingido. Envie Retry-After. |
500 | Internal Server Error | Erro inesperado no servidor. |
503 | Service Unavailable | Fora do ar temporariamente ou sobrecarregado. |
Desenhando as rotas
| Ação | Requisição | Resposta de sucesso |
|---|---|---|
| Listar | GET /trilhas?nivel=iniciante&pagina=2 | 200 com a lista |
| Detalhar | GET /trilhas/42 | 200, ou 404 se não existir |
| Criar | POST /trilhas | 201 com Location |
| Substituir | PUT /trilhas/42 | 200 ou 204 |
| Alterar | PATCH /trilhas/42 | 200 com o recurso atualizado |
| Remover | DELETE /trilhas/42 | 204 |
- Use substantivos no plural na URL e deixe o verbo para o método:
POST /trilhas, não/criarTrilha. - Filtros, ordenação e paginação vão na query string.
- Relações aparecem no caminho quando fazem sentido:
/trilhas/42/passos. - Devolva erros sempre no mesmo formato, para o cliente poder mostrar a mensagem certa.
Um corpo de erro no formato da RFC 9457 (application/problem+json)
{
"type": "https://api.trilha.info/erros/validacao",
"title": "Dados inválidos",
"status": 422,
"detail": "O campo texto não pode ficar vazio.",
"instance": "/trilhas/42/anotacoes"
}Quando uma chamada falha
Leia o status antes do resto
Ele diz de que lado está o problema:
4xxaponta para a requisição,5xxpara o servidor.Com 4xx, confira a requisição
URL, método,
Content-Type, corpo e token. Compare com a documentação e com um exemplo que funciona.Com 5xx, procure os logs do servidor
O cliente raramente vê a causa. Um identificador de requisição na resposta ajuda a encontrar o log.
Erro de CORS no navegador?
A requisição pode ter chegado ao servidor. O que faltou foi ele autorizar a origem com
Access-Control-Allow-Origin.