DEV Community

Vinícius Carregosa
Vinícius Carregosa

Posted on

Métodos HTTP: entendendo GET, POST, PUT, PATCH e DELETE

#webdev #api #backend #programming

Imagine que estamos desenvolvendo uma API para gerenciar usuários. Precisamos consultar os usuários cadastrados, criar novos registros, atualizar informações e excluir aqueles que não são mais necessários.

Todas essas operações podem acontecer por meio de requisições HTTP. Mas existe uma questão: como o servidor sabe o que queremos fazer com determinado recurso?

É aí que entram os métodos HTTP.

O que são métodos HTTP?

Os métodos HTTP indicam a intenção de uma requisição. Eles comunicam ao servidor qual operação o cliente deseja realizar sobre um determinado recurso.

Podemos fazer uma analogia com uma biblioteca.

Imagine que você chega até o balcão e pode solicitar diferentes ações: consultar um livro, cadastrar um novo exemplar, atualizar informações do catálogo ou remover um registro. O objeto continua sendo um livro, mas a ação solicitada muda.

Nas APIs, acontece algo semelhante. O recurso pode ser um usuário, um produto, um pedido ou qualquer outra entidade disponibilizada pelo sistema. O método HTTP indica o que queremos fazer com ele.

Os métodos mais utilizados no desenvolvimento de APIs são GET, POST, PUT, PATCH e DELETE.

GET — Consultar recursos

O método GET é utilizado para solicitar a representação de um recurso ao servidor.

Imagine que queremos consultar os usuários cadastrados em nossa aplicação. Poderíamos fazer a seguinte requisição:

GET /api/usuarios HTTP/1.1
Host: api.exemplo.com
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

O servidor processa a solicitação e pode retornar uma resposta com os dados:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "nome": "Vinicius",
    "email": "vinicius@email.com"
  },
  {
    "id": 2,
    "nome": "Mariana",
    "email": "mariana@email.com"
  }
]
Enter fullscreen mode Exit fullscreen mode

Também podemos consultar um recurso específico:

GET /api/usuarios/1 HTTP/1.1
Enter fullscreen mode Exit fullscreen mode

Nesse caso, estamos solicitando o usuário cujo identificador é 1.

Uma característica importante do GET é que ele deve ser um método seguro (safe). Isso significa que sua semântica não prevê alterações no estado do recurso no servidor.

Por exemplo, consultar um usuário não deveria alterar seus dados, excluir registros ou realizar uma operação financeira.

Isso não significa que a requisição não possa gerar efeitos indiretos, como registros de acesso ou métricas. A questão é que a operação solicitada não deve modificar o estado do recurso.

POST — Criar ou processar recursos

O POST é utilizado para enviar dados ao servidor, geralmente para criar um novo recurso ou executar uma operação cuja semântica é definida pela aplicação.

Imagine que queremos cadastrar um usuário. A requisição poderia ser:

POST /api/usuarios HTTP/1.1
Host: api.exemplo.com
Content-Type: application/json

{
  "nome": "Carlos",
  "email": "carlos@email.com"
}
Enter fullscreen mode Exit fullscreen mode

O servidor recebe os dados, realiza as validações necessárias e, caso tudo esteja correto, pode criar o registro.

Uma resposta comum seria:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 3,
  "nome": "Carlos",
  "email": "carlos@email.com"
}
Enter fullscreen mode Exit fullscreen mode

Observe que utilizamos o status 201 Created, indicando que um recurso foi criado.

Mas POST não serve exclusivamente para cadastros. Ele também pode ser utilizado para operações como processamento de pagamentos, envio de mensagens ou execução de determinadas ações.

O significado depende do recurso e da operação disponibilizada pela API.

PUT — Substituir um recurso

O PUT é utilizado para criar ou substituir o estado de um recurso identificado pela URI, conforme a semântica definida pelo servidor.

Imagine que temos um usuário cadastrado:

{
  "id": 1,
  "nome": "Vinicius",
  "email": "vinicius@email.com"
}
Enter fullscreen mode Exit fullscreen mode

Queremos atualizar seus dados para:

{
  "nome": "Vinicius Andrade",
  "email": "vinicius.andrade@email.com"
}
Enter fullscreen mode Exit fullscreen mode

Podemos utilizar:

PUT /api/usuarios/1 HTTP/1.1
Host: api.exemplo.com
Content-Type: application/json

{
  "nome": "Vinicius Andrade",
  "email": "vinicius.andrade@email.com"
}
Enter fullscreen mode Exit fullscreen mode

A ideia do PUT é enviar uma representação para substituir o estado atual do recurso.

Por isso, precisamos ter cuidado com a diferença entre PUT e uma atualização parcial.

Se a API espera uma representação completa do recurso, enviar apenas o nome pode fazer com que outros campos sejam removidos, redefinidos ou tratados conforme as regras de implementação.

O comportamento exato depende do contrato da API, mas não devemos assumir que PUT significa simplesmente atualizar qualquer campo que foi enviado.

PATCH — Atualizar parcialmente um recurso

O PATCH também é utilizado para modificar recursos, mas sua proposta é aplicar alterações parciais.

Vamos imaginar que queremos alterar somente o e-mail de um usuário, sem precisar enviar novamente todas as informações.

A requisição poderia ser:

PATCH /api/usuarios/1 HTTP/1.1
Host: api.exemplo.com
Content-Type: application/json

{
  "email": "novo.email@email.com"
}
Enter fullscreen mode Exit fullscreen mode

Nesse cenário, o servidor interpreta os dados recebidos e aplica a alteração solicitada.

Uma diferença importante: o HTTP não determina que todo PATCH deve receber um JSON com apenas os campos alterados. O formato da operação depende do contrato da API e do tipo de representação utilizado.

Por exemplo, existem formatos específicos para operações de PATCH, como JSON Patch e JSON Merge Patch.

A escolha entre PUT e PATCH depende de como queremos representar a atualização:

  • PUT: enviar uma representação para substituir o estado do recurso.
  • PATCH: enviar instruções ou dados para modificar parcialmente o recurso.

DELETE — Remover recursos

O DELETE solicita a remoção da associação entre a URI e sua funcionalidade ou recurso atual.

Imagine que queremos excluir o usuário de identificador 1:

DELETE /api/usuarios/1 HTTP/1.1
Host: api.exemplo.com
Enter fullscreen mode Exit fullscreen mode

Se a operação for concluída, o servidor pode responder:

HTTP/1.1 204 No Content
Enter fullscreen mode Exit fullscreen mode

O status 204 indica que a solicitação foi processada com sucesso e não há conteúdo adicional na resposta.

Uma observação: DELETE não significa necessariamente que os dados serão apagados fisicamente do banco de dados. A aplicação pode utilizar exclusão lógica, por exemplo, apenas marcando o registro como inativo.

O método representa a intenção de remover o recurso, enquanto a implementação define como isso será realizado.

Segurança e idempotência: duas propriedades importantes

Além de conhecer a finalidade de cada método, precisamos entender duas propriedades que aparecem frequentemente na documentação HTTP: segurança (safe) e idempotência (idempotent).

Elas ajudam a definir como uma operação deve se comportar, especialmente quando lidamos com repetição de requisições, falhas de rede e integrações entre sistemas.

O que significa um método ser seguro?

Um método seguro é aquele cuja semântica não prevê alterações no estado do recurso no servidor.

Isso não significa que a requisição não gere nenhum efeito. O servidor ainda pode registrar logs, atualizar métricas ou contabilizar acessos.

O ponto principal é que a operação solicitada pelo cliente não deve modificar o estado do recurso.

GET é um exemplo de método seguro.

O que significa idempotência?

Idempotência é uma propriedade que indica que executar uma mesma operação uma ou várias vezes produz o mesmo efeito pretendido no estado do servidor.

Imagine que enviamos uma requisição para atualizar o e-mail de um usuário:

PUT /api/usuarios/1 HTTP/1.1
Content-Type: application/json

{
  "nome": "Vinicius",
  "email": "vinicius@email.com"
}
Enter fullscreen mode Exit fullscreen mode

Se enviarmos essa mesma requisição cinco vezes, o resultado pretendido continuará sendo o mesmo: o usuário terá aquele nome e aquele e-mail.

A operação é idempotente porque repetir a solicitação não produz alterações adicionais no estado pretendido.

Agora imagine uma requisição POST responsável por criar um pedido.

Se enviarmos a mesma solicitação cinco vezes, podemos acabar criando cinco pedidos diferentes, dependendo da implementação.

Por isso, POST não é idempotente por definição.

Essa diferença é especialmente importante em sistemas distribuídos. Imagine que um cliente envia uma requisição, mas a conexão cai antes de receber a resposta. Ele não sabe se o servidor processou a operação.

Se repetir a solicitação, pode acabar executando a mesma ação novamente.

Em operações financeiras, por exemplo, isso pode ser um problema. Por essa razão, algumas APIs utilizam mecanismos como chaves de idempotência (Idempotency Keys) para evitar que uma mesma operação seja processada mais de uma vez.

Comparando os métodos

Método Finalidade comum Seguro? Idempotente?
GET Consultar recursos Sim Sim
POST Criar ou processar operações Não Não, por definição
PUT Criar ou substituir um recurso Não Sim
PATCH Modificar parcialmente um recurso Não Não necessariamente
DELETE Remover um recurso Não Sim

Uma observação sobre PATCH: ele pode ser implementado de maneira idempotente ou não, dependendo da operação. Por exemplo, definir o e-mail de um usuário para um valor específico tende a ser idempotente. Já uma operação que incrementa um contador não é.

Também é importante entender que idempotência não significa que todas as respostas HTTP serão iguais. Uma primeira requisição DELETE pode retornar 204, enquanto uma segunda pode retornar 404. Mesmo assim, o efeito pretendido sobre o estado do recurso pode continuar sendo o mesmo: ele permanece removido.

Como isso aparece em uma API REST?

Em uma API REST, normalmente trabalhamos com recursos identificados por URIs e utilizamos os métodos HTTP para expressar as operações desejadas.

Imagine uma API de gerenciamento de produtos:

Requisição Operação
GET /api/produtos Listar produtos
GET /api/produtos/10 Consultar um produto
POST /api/produtos Criar um produto
PUT /api/produtos/10 Substituir os dados de um produto
PATCH /api/produtos/10 Alterar parte dos dados de um produto
DELETE /api/produtos/10 Remover um produto

Observe que o caminho identifica o recurso e o método expressa a operação.

Essa organização torna as APIs mais previsíveis. Um desenvolvedor que conhece os princípios básicos do HTTP consegue compreender boa parte das operações disponíveis apenas observando suas rotas e métodos.

Isso também facilita a integração entre diferentes aplicações e serviços.

Por que entender os métodos HTTP faz diferença?

Em projetos reais, escolher corretamente um método HTTP não é apenas uma questão de organização.

Essa decisão influencia o contrato da API, a previsibilidade das operações, o comportamento de clientes e a maneira como falhas e repetições são tratadas.

Em uma arquitetura com API Gateway e microsserviços, por exemplo, o Gateway recebe requisições HTTP e pode encaminhá-las para os serviços responsáveis pelos recursos.

Se uma operação de atualização foi definida como PUT, enquanto outra utiliza PATCH, essa distinção precisa ser respeitada pelos consumidores da API e pelos componentes envolvidos na comunicação.

Também é importante lembrar que o método

Top comments (0)