Desenvolvendo APIs

Minimal APIs

O Lino adota o estilo Minimal API como padrão para geração de endpoints, priorizando:

• Clareza – código enxuto, direto e expressivo.
• Performance – respostas otimizadas, sem overhead desnecessário.

Recursos integrados

TypedResults: garantem respostas fortemente tipadas, auxiliando na legibilidade e na geração de OpenAPI.

Versionamento de APIs: endpoints podem ser evoluídos sem quebrar compatibilidade.

Documentação enriquecida: metadados configuráveis são incorporados diretamente no OpenAPI, incluindo:

• WithTags → agrupa endpoints em seções lógicas no OpenAPI.
• WithName → define o operationId de forma consistente.
• WithSummary → descreve claramente o propósito do endpoint.
• Produces(statusCode, schema) → especifica códigos de status e contratos de resposta.
• MapToApiVersion → permite expor diferentes versões do mesmo endpoint.

Requests e Responses

Record classes são utilizadas para Requests e Responses por padrão:

• São imutáveis (reduzindo efeitos colaterais e bugs).
• São concisas e de fácil leitura.

Integração com CQRS:

• Requests recebidos via endpoints são transformados em Commands ou Queries.
• Os resultados de Commands/Queries são convertidos em Responses, promovendo consistência arquitetural.

Exemplo simplificado:
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

Criando novas APIs

Criar um endpoint com a CLI do Lino é simples:

lino new api

O assistente interativo solicitará:

• Serviço – serviço no qual a API será criada.
• Módulo – módulo do serviço (quando aplicável).
• Entidade – entidade associada ao endpoint.
• Nome da API – normalmente alinhado ao verbo da operação (ex.: CreatePerson).
• Tipo de operação – POST, PUT, PATCH, DELETE ou GET.
• Rota – padrão de rota (ex.: /people/{id}).

Exemplo:

Ao criar uma API POST chamada CreatePerson, associada à entidade Person, o CLI gera automaticamente:

• Endpoint com mapeamento HTTP.
• DTOs de Request e Response.
• Extensions para integração com OpenAPI e versionamento.

Estrutura gerada:

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Api/
                └── MyApp.MyService.Api.csproj
                    └── Endpoints/
                        └── People/
                            └── CreatePerson/
                                ├── CreatePersonEndpoint.cs
                                ├── CreatePersonExtensions.cs
                                ├── CreatePersonRequest.cs
                                └── CreatePersonResponse.cs

Nos projetos que possuem aplicações Web Blazor adicionadas, o Lino gera automaticamente os artefatos necessários para o consumo das APIs.
Isso inclui os contratos compartilhados (Request e Response/DTOs), a interface do client e uma implementação padrão para chamadas HTTP, permitindo que o Blazor consuma as APIs de forma simples, tipada e consistente.

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Api/
                ├── MyApp.MyService.Api.Contracts.csproj
                │   └── Features/
                │       └── People/
                │           ├── CreatePerson/
                │           │   ├── CreatePersonRequest.cs
                │           │   └── CreatePersonResponse.cs
                │           └── IPersonApiClient.cs
                └── MyApp.MyService.Api.Client.csproj
                    └── Features/
                        └── PersonApiClient.cs

Registro de Endpoints com Source Generators

O Lino elimina a necessidade de mapeamento manual de endpoints ou uso intensivo de Reflection em tempo de execução.
Em vez disso, utiliza Source Generators para produzir automaticamente o código de registro durante a compilação.

Como funciona

Para cada endpoint criado, o generator gera classes/parciais que chamam:
MapGet, MapPost, MapPut, MapDelete, etc.

Isso substitui a necessidade de adicionar manualmente todos os mapeamentos em Program.cs.

Vantagens:

• Registro em tempo de compilação → evita erros de runtime.
• Program.cs enxuto → menor superfície de configuração manual.
• Compatibilidade AOT → elimina dependência de Reflection.
• Documentação integrada → metadados (tags, summary, produces) são gerados junto ao mapeamento.

Esse modelo garante que as APIs criadas no Lino sejam:

• Auto-documentadas
• Performáticas
• Consistentes com a arquitetura CQRS do framework.