Controllers e roteamento

Resumo

Controllers de API herdam de ControllerBase e usam attribute routing para mapear URLs a ações. Entender roteamento e a nomeação de recursos é o alicerce de uma API RESTful clara.

1. Objetivos de Aprendizagem#

• Criar um controller de API com [ApiController] e ControllerBase.
• Configurar rotas com atributos e templates.
• Nomear recursos seguindo convenções REST.

2. Pré-requisitos#

• Repository/Service Layer do Módulo 17.

3. Conceito#

O diagrama abaixo resume o fluxo principal.

Em uma Web API usamos ControllerBase (sem suporte a Views). O atributo [ApiController] habilita comportamentos: validação automática de ModelState, inferência de binding e respostas 400 padronizadas. As rotas são baseadas em atributos ([Route], [HttpGet]), não em convenções de MVC.

Convenção REST: recursos são substantivos no plural (/api/categorias), e a hierarquia expressa relacionamento (/api/categorias/{id}/produtos).

4. Mão na Massa#

4.1. Setup#

Certifique-se de que app.MapControllers() está no pipeline.

4.2. Implementação Passo a Passo#

1. Controller base:

using Microsoft.AspNetCore.Mvc;

namespace Catalog.Api.Controllers;

[ApiController]
[Route("api/categorias")]
public class CategoriasController : ControllerBase
{
    [HttpGet]
    public IActionResult GetCategorias() => Ok(new[] { "exemplo" });
}

2. Rota com parâmetro e nome (para geração de links):

[HttpGet("{id:guid}", Name = "CategoriaById")]
public IActionResult GetCategoria(Guid id) => Ok(new { id });

O route constraint :guid rejeita valores que não sejam GUID.

4.3. Executando#

dotnet run
curl http://localhost:5000/api/categorias

5. Exemplo Completo#

[ApiController]
[Route("api/categorias")]
public class CategoriasController : ControllerBase
{
    [HttpGet]
    public IActionResult GetCategorias() => Ok();

    [HttpGet("{id:guid}", Name = "CategoriaById")]
    public IActionResult GetCategoria(Guid id) => Ok(new { id });
}

6. Boas Práticas e Armadilhas#

Atenção

[ApiController] torna a validação de ModelState automática — não retorne 400 manualmente para erros de modelo, isso já é feito para você (ver Módulo 27).

7. Segurança e Produção#

• Nunca exponha detalhes internos na rota (ex.: nomes de tabela). A URL é parte do contrato público.
• Combine rotas com atributos de autorização (Módulo 40) para proteger recursos sensíveis.

8. Exercícios#

• Fácil: adicione um controller ProdutosController com GET em /api/produtos.
• Médio: crie uma rota aninhada /api/categorias/{categoriaId}/produtos.
• Desafio: adicione um constraint customizado que aceite apenas GUIDs não vazios.

9. Resumo#

Controllers de API herdam de ControllerBase, usam attribute routing e [ApiController]. Recursos são nomeados como substantivos no plural, com constraints garantindo URLs válidas.

10. Próximos Passos#

A seguir retornamos dados reais do banco via repositório.

11. Referências#

• Microsoft Learn — Roteamento no ASP.NET Core
• Microsoft Learn — Criar APIs web com ASP.NET Core
• Microsoft Learn — Atributo ApiController