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 OK ou 204 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 header Allow

🔹 **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