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
