Guia de Verbos HTTPem ASP.NET Core Web API
Quando desenvolvemos APIs com .NET, é fundamental entender como utilizar corretamente os verbo HTTP (GET, POST, PUT, PATCH, DELETE, etc.) e como retornar os status codes apropriados.
Este artigo apresenta um guia direto e objetivo sobre os principais verbos HTTP, seus usos ideais e os retornos recomendados para cada um, com exemplos reais em C#.
📌 GET – Recuperar dados
Uso: Listar ou buscar recursos (como por ID).
Respostas comuns:
- ✅
200 OK: Recurso(s) encontrado(s) - ❌
404 NotFound: Recurso não encontrado
[HttpGet("{id}")]
public IActionResult Get(int id)
{
var item = _service.GetById(id);
if (item == null)
return NotFound();
return Ok(item);
}
📌 POST – Criar recurso
Uso: Criar um novo recurso.
Respostas comuns:
- ✅
201 Created: Criado com sucesso - ⚠️
400 BadRequest: Dados inválidos - ⚠️
409 Conflict: Conflito (por exemplo, duplicidade)
[HttpPost]
public IActionResult Create([FromBody] ResourceDto dto)
{
if (!ModelState.IsValid)
return BadRequest(ModelState);
var created = _service.Create(dto);
return CreatedAtAction(nameof(Get), new { id = created.Id }, created);
}
📌 PUT – Atualizar recurso por completo
Uso: Substituir um recurso existente.
Respostas comuns:
- ✅
200 OK: Atualizado e retornado - ✅
204 NoContent: Atualizado, sem retorno - ⚠️
400 BadRequest: Dados inválidos - ❌
404 NotFound: Recurso não encontrado - ⚠️
409 Conflict: Conflito de atualização
[HttpPut("{id}")]
public IActionResult Update(int id, [FromBody] ResourceDto dto)
{
if (!ModelState.IsValid)
return BadRequest(ModelState);
var updated = _service.Update(id, dto);
if (updated == null)
return NotFound();
return Ok(updated);
}
📌 PATCH – Atualização parcial
Uso: Alterar parcialmente um recurso.
Respostas comuns:
- ✅
200 OKou204 NoContent: Atualização parcial feita - ⚠️
400 BadRequest: Dados inválidos - ❌
404 NotFound: Recurso não encontrado - ⚠️
409 Conflict: Conflito
[HttpPatch("{id}")]
public IActionResult Patch(int id, [FromBody] JsonPatchDocument<ResourceDto> patch)
{
var resource = _service.GetById(id);
if (resource == null)
return NotFound();
patch.ApplyTo(resource, ModelState);
if (!ModelState.IsValid)
return BadRequest(ModelState);
_service.Update(id, resource);
return Ok(resource);
}
📌 DELETE – Remover recurso
Uso: Remover recurso existente.
Respostas comuns:
- ✅
204 NoContent: Recurso removido com sucesso - ❌
404 NotFound: Recurso não encontrado
[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
var exists = _service.Exists(id);
if (!exists)
return NotFound();
_service.Delete(id);
return NoContent();
}
📌 HEAD – Somente os headers
Uso: Obter apenas os headers da resposta (sem corpo).
Respostas comuns:
- ✅
200 OK: Recurso existe - ❌
404 NotFound: Recurso não encontrado
Obs: Geralmente usado para verificações automáticas ou caching.
📌 OPTIONS – Métodos suportados
Uso: Descobrir quais métodos HTTP são aceitos por um endpoint.
Resposta comum:
- ✅
200 OK: Métodos listados no headerAllow
🔹 **GET**
- ✅ Sucesso: `200 OK`
- ❌ Erros comuns: `404 NotFound`
- 📦 Retornos (.NET): `Ok()`, `NotFound()`
🔹 **POST**
- ✅ Sucesso: `201 Created`
- ❌ Erros comuns: `400 BadRequest`, `409 Conflict`
- 📦 Retornos (.NET): `CreatedAtAction()`, `BadRequest()`, `Conflict()`
🔹 **PUT**
- ✅ Sucesso: `200 OK`, `204 NoContent`
- ❌ Erros comuns: `400 BadRequest`, `404 NotFound`, `409 Conflict`
- 📦 Retornos (.NET): `Ok()`, `NoContent()`, `BadRequest()`, `Conflict()`
🔹 **PATCH**
- ✅ Sucesso: `200 OK`, `204 NoContent`
- ❌ Erros comuns: `400 BadRequest`, `404 NotFound`, `409 Conflict`
- 📦 Retornos (.NET): `Ok()`, `NoContent()`, `BadRequest()`, `Conflict()`
🔹 **DELETE**
- ✅ Sucesso: `204 NoContent`
- ❌ Erros comuns: `404 NotFound`
- 📦 Retornos (.NET): `NoContent()`, `NotFound()`
🔹 **HEAD**
- ✅ Sucesso: `200 OK`
- ❌ Erros comuns: `404 NotFound`
- 📦 Retornos: *(Sem corpo)*
🔹 **OPTIONS**
- ✅ Sucesso: `200 OK`
- 📦 Retornos: *(Sem corpo)*
📚 Referências
- Microsoft REST API Guidelines
- Documentação oficial do ASP.NET Core Web API
💬 Conclusão
Entender o uso correto dos verbos HTTP e seus respectivos retornos é essencial para criar APIs bem definidas e compatíveis com boas práticas do mercado. Com essas dicas, você garante uma API mais consistente, previsível e fácil de manter.
Se você curtiu esse conteúdo, compartilhe com colegas devs e vamos fortalecer a comunidade! 🚀
Repositório disponível em: https://github.com/GianLost/HTTP-Documentation
Olá, conforme a questão apresentada, um dos principais benefícios senão o maior de se utilizar corretamente os verbos HTTP conforme o contexto adequado é a clareza e o entendimento por parte de quem consome a API. Quando uma API é bem estruturada, com endpoints semanticamente definidos e alinhados aos princípios REST, evitam-se situações em que o consumidor precisa recorrer a documentações extensas ou realizar testes por tentativa e erro para compreender o funcionamento dos endpoints.
Além disso, há um ganho significativo em termos de implantação, manutenção e testes. Com uma estrutura padronizada e semanticamente coerente, é possível alcançar maior eficiência nessas etapas. O uso adequado dos status codes HTTP também colabora diretamente com a identificação e correção de erros, especialmente em ambientes de desenvolvimento. Isso otimiza etapas como o controle de qualidade (QA), uma vez que os retornos apropriados fornecem informações mais precisas sobre falhas e facilitam o processo de depuração.
Embora tecnicamente seja possível utilizar apenas o verbo POST para diversas operações, essa abordagem compromete a semântica da API e dificulta sua compreensão, manutenção e evolução. Assim, embora pareça um caminho mais fácil, não é, necessariamente, o mais adequado. A adoção correta dos verbos HTTP e dos códigos de status promove padronização, previsibilidade e uma melhor experiência para os desenvolvedores que consomem a API.
Excelente, Gianluca! Seu artigo sobre Guia de Verbos HTTP em ASP.NET Core Web API é super claro e prático. É fascinante ver como você aborda o uso correto dos verbos HTTP (GET, POST, PUT, PATCH, DELETE) e como retornar os status codes apropriados para cada um, com exemplos reais em C#.
Você demonstrou os retornos recomendados para cada verbo, como 200 OK para GET e 201 Created para POST, e os possíveis erros, como 404 NotFound e 400 BadRequest. Sua análise do HEAD e OPTIONS para verificações automáticas e caching, e o resumo de cada verbo, é fundamental para quem busca criar APIs bem definidas, consistentes, previsíveis e fáceis de manter.
Considerando que "entender o uso correto dos verbos HTTP e seus respectivos retornos é essencial para criar APIs bem definidas e compatíveis com boas práticas do mercado", qual você diria que é o maior benefício para um desenvolvedor ao utilizar os verbos HTTP de forma semântica e os status codes de forma correta, em termos de clareza e previsibilidade da API para quem a consome, em vez de usar um POST para todas as operações?
SHOW hein, sempre bom relembrar!! 🤓