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

Os métodos mais usados em APIs
MétodoUsoSeguroIdempotente
GETLer um recurso ou uma listaSimSim
POSTCriar um recurso ou disparar uma açãoNãoNão
PUTSubstituir um recurso inteiroNãoSim
PATCHAlterar parte de um recursoNãoNão garantido
DELETERemover um recursoNãoSim
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.

Os códigos que você mais vai ver
CódigoNomeQuando usar
200OKLeitura ou alteração bem-sucedida, com corpo.
201CreatedRecurso criado. Envie Location com o endereço dele.
204No ContentDeu certo e não há o que devolver, como em um DELETE.
304Not ModifiedO cliente pode usar a cópia que já tem em cache.
400Bad RequestCorpo ou parâmetros malformados.
401UnauthorizedFalta autenticação, ou ela é inválida.
403ForbiddenAutenticado, mas sem permissão.
404Not FoundO recurso não existe, ou você não deve saber que existe.
409ConflictConflita com o estado atual, como um e-mail já cadastrado.
422Unprocessable ContentFormato correto, mas a validação falhou.
429Too Many RequestsLimite de requisições atingido. Envie Retry-After.
500Internal Server ErrorErro inesperado no servidor.
503Service UnavailableFora do ar temporariamente ou sobrecarregado.

Desenhando as rotas

Um recurso, seis operações
AçãoRequisiçãoResposta de sucesso
ListarGET /trilhas?nivel=iniciante&pagina=2200 com a lista
DetalharGET /trilhas/42200, ou 404 se não existir
CriarPOST /trilhas201 com Location
SubstituirPUT /trilhas/42200 ou 204
AlterarPATCH /trilhas/42200 com o recurso atualizado
RemoverDELETE /trilhas/42204
  • 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

  1. Leia o status antes do resto

    Ele diz de que lado está o problema: 4xx aponta para a requisição, 5xx para o servidor.

  2. 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.

  3. 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.

  4. 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.

Referências

Trilhas relacionadas