Resumo

O Root Document é o ponto de entrada da API (GET /api): uma resposta com links para os principais recursos, permitindo que clientes descubram a API a partir de uma única URL.

1. Objetivos de Aprendizagem#

Implementar um endpoint raiz com links de descoberta.
Reutilizar LinkGenerator e media type customizado.
Entender o papel do Root Document em APIs hypermedia.

2. Pré-requisitos#

HATEOAS (Módulo 35).

3. Conceito#

O Root Document materializa a ideia de HATEOAS no nível da API inteira: o cliente conhece uma URL e, a partir dela, segue links para tudo. O porquê: desacoplamento total de URLs — o servidor pode reorganizar endpoints e o cliente continua funcionando, pois navega por rel.

4. Mão na Massa#

4.1. Setup#

Reuse LinkGenerator e o media type customizado do Módulo 35.

4.2. Implementação Passo a Passo#

Controller raiz:

[ApiController]
[Route("api")]
public class RootController : ControllerBase
{
    private readonly LinkGenerator _links;
    public RootController(LinkGenerator links) => _links = links;

    [HttpGet(Name = "GetRoot")]
    public IActionResult GetRoot([FromHeader(Name = "Accept")] string mediaType)
    {
        if (!mediaType.Contains("vnd.catalog.apiroot", StringComparison.OrdinalIgnoreCase))
            return NoContent();

        var links = new List<Link>
        {
            new(_links.GetUriByName(HttpContext, "GetRoot", new {}), "self", "GET"),
            new(_links.GetUriByName(HttpContext, "GetCategorias", new {}),
                "categorias", "GET"),
            new(_links.GetUriByName(HttpContext, "CreateCategoria", new {}),
                "create_categoria", "POST"),
        };
        return Ok(links);
    }
}

Garanta que as rotas referenciadas tenham Name (ex.: GetCategorias, CreateCategoria).

4.3. Executando#

Shell

curl -H "Accept: application/vnd.catalog.apiroot+json" http://localhost:5000/api

5. Exemplo Completo#

JSON

[
  { "href": "http://localhost:5000/api", "rel": "self", "method": "GET" },
  { "href": "http://localhost:5000/api/categorias", "rel": "categorias", "method": "GET" },
  { "href": "http://localhost:5000/api/categorias", "rel": "create_categoria", "method": "POST" }
]

6. Boas Práticas e Armadilhas#

Faça	Evite
Nomear todas as rotas referenciadas no root	Referenciar rotas sem `Name` (gera link nulo)
Condicionar o root ao media type de descoberta	Poluir o `GET /api` padrão
Listar só os recursos de topo	Enumerar toda a árvore de endpoints

Atenção

se uma rota referenciada não tiver Name, o LinkGenerator retorna null e o link fica quebrado. Padronize os nomes de rota.

7. Segurança e Produção#

Exponha no root apenas recursos que o cliente pode alcançar; para APIs autenticadas, adapte os links ao contexto do usuário.

8. Exercícios#

Fácil: adicione um link para o endpoint de produtos.
Médio: retorne 404/NoContent de forma clara quando o media type não for o de descoberta.
Desafio: gere o root automaticamente a partir dos endpoints anotados.

9. Resumo#

O Root Document é a porta de entrada navegável da API, entregando links de descoberta condicionados a um media type próprio. Depende de rotas nomeadas e do LinkGenerator.

10. Próximos Passos#

Módulo 37: versionamento de APIs.

11. Referências#

Microsoft Learn — LinkGenerator
Richardson Maturity Model — REST nível 3
Microsoft Learn — Roteamento por atributos