Implementando OPTIONS e HEAD

Resumo

OPTIONS informa quais métodos um recurso suporta (cabeçalho Allow); HEAD retorna os mesmos cabeçalhos de um GET, porém sem corpo. Ambos são seguros e idempotentes.

1. Objetivos de Aprendizagem#

• Implementar OPTIONS retornando o cabeçalho Allow.
• Implementar HEAD reaproveitando a lógica do GET.
• Entender o uso desses métodos por clientes e ferramentas.

2. Pré-requisitos#

• Verbos HTTP e safety/idempotência (Módulos 04 e 08).

3. Conceito#

• OPTIONS responde 200 OK com Allow: GET, POST, OPTIONS, comunicando as operações disponíveis. É usado, por exemplo, no preflight de CORS.
• HEAD é como GET sem corpo: o cliente obtém metadados (tamanho, ETag, Last-Modified) sem baixar a representação. O porquê: economia de banda em verificações.

4. Mão na Massa#

4.1. Setup#

Sem pacotes novos.

4.2. Implementação Passo a Passo#

1. OPTIONS:

[HttpOptions]
public IActionResult GetOptions()
{
    Response.Headers.Allow = "GET, OPTIONS, POST";
    return Ok();
}

2. HEAD compartilhando a ação do GET:

[HttpGet]
[HttpHead] // a mesma ação responde GET e HEAD; o framework descarta o corpo no HEAD
public async Task<IActionResult> Get()
{
    var produtos = await _service.Produto.GetAllAsync(false);
    return Ok(produtos);
}

4.3. Executando#

curl -i -X OPTIONS http://localhost:5000/api/produtos      # header Allow
curl -I http://localhost:5000/api/produtos                 # HEAD: só cabeçalhos

5. Exemplo Completo#

Ao anotar a ação com [HttpGet] e [HttpHead], o ASP.NET Core executa a lógica e automaticamente omite o corpo na resposta ao HEAD, mantendo os cabeçalhos (incluindo Content-Length).

6. Boas Práticas e Armadilhas#

Atenção

HEAD não deve ter corpo. Se você escrever manualmente no Response.Body, o cliente pode receber Content-Length incorreto — deixe o framework cuidar disso.

7. Segurança e Produção#

• OPTIONS é parte do preflight CORS; a política de CORS (Módulo 16) precisa permitir os métodos anunciados.

8. Exercícios#

• Fácil: adicione OPTIONS a outro controller.
• Médio: confirme que o HEAD retorna o mesmo Content-Length do GET.
• Desafio: gere o cabeçalho Allow dinamicamente a partir dos métodos mapeados na rota.

9. Resumo#

OPTIONS anuncia métodos suportados via Allow; HEAD reaproveita o GET sem corpo. Ambos são seguros, idempotentes e úteis a clientes e ao CORS.

10. Próximos Passos#

Módulo 36: o Root Document, ponto de entrada navegável da API.

11. Referências#

• MDN — OPTIONS
• MDN — HEAD
• Microsoft Learn — Roteamento e atributos de verbo HTTP