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 o CLI do Lino é simples:

lino new api

O assistente interativo solicitará:

• Serviço – serviço em que 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.
• Request/Response DTOs.
• Extensions para integração com OpenAPI e versionamento.
• HttpClient tipado para consumo interno por outros serviços.

Estrutura gerada:

MyApp/
└── src/
    ├── Services/
    │   └── MyService/
    │       └── Presentation.API/
    │           ├── MyApp.MyService.Presentation.API.csproj
    │           └── Endpoints/
    │               └── People/
    │                   └── CreatePerson/
    │                       ├── CreatePersonEndpoint.cs
    │                       ├── CreatePersonExtensions.cs
    │                       ├── CreatePersonRequest.cs
    │                       └── CreatePersonResponse.cs
    └── Integrations/
        └── MyService/
            └── Http/
                ├── Contracts/
                │   └── Apis/
                │       └── People/
                │           ├── IPersonHttpClient.cs
                │           └── CreatePerson/
                │               ├── CreatePersonRequest.cs
                │               └── CreatePersonResponse.cs
                └── Clients/
                    └── Apis/
                        └── PersonHttpClient.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.