Desarrollo de APIs

Minimal APIs

Lino adopta el estilo Minimal API como estándar para la generación de endpoints, priorizando:

• Claridad – código conciso, directo y expresivo.
• Rendimiento – respuestas optimizadas, sin sobrecarga innecesaria.

Recursos integrados

TypedResults: garantizan respuestas fuertemente tipadas, ayudando a la legibilidad y a la generación de OpenAPI.

Versionado de APIs: los endpoints pueden evolucionar sin romper compatibilidad.

Documentación enriquecida: los metadatos configurables se incorporan directamente en OpenAPI, incluyendo:

• WithTags → agrupa endpoints en secciones lógicas en OpenAPI.
• WithName → define el operationId de forma consistente.
• WithSummary → describe claramente el propósito del endpoint.
• Produces(statusCode, schema) → especifica códigos de estado y contratos de respuesta.
• MapToApiVersion → permite exponer diferentes versiones del mismo endpoint.

Requests y Responses

Record classes se utilizan por defecto para Requests y Responses:

• Son inmutables (reduciendo efectos secundarios y errores).
• Son concisas y fáciles de leer.

Integración con CQRS:

• Las Requests recibidas a través de los endpoints se transforman en Commands o Queries.
• Los resultados de Commands/Queries se convierten en Responses, promoviendo consistencia arquitectural.

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

Creación de nuevas API

Crear un endpoint con la CLI de Lino es muy sencillo:

lino new api

El asistente interactivo solicitará:

• Servicio – el servicio en el que se creará la API.
• Módulo – el módulo del servicio (cuando corresponda).
• Entidad – la entidad asociada al endpoint.
• Nombre de la API – normalmente alineado con el verbo de la operación (ej.: CreatePerson).
• Tipo de operación – POST, PUT, PATCH, DELETE o GET.
• Ruta – patrón de la ruta (ej.: /people/{id}).

Ejemplo:

Al crear una API POST llamada CreatePerson asociada a la entidad Person, la CLI genera automáticamente:

• Endpoint con mapeo HTTP.
• Request/Response DTO.
• Extensiones para integración con OpenAPI y versionado.
• HttpClient tipado para uso interno por otros servicios.

Estructura generada:

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 con Source Generators

Lino elimina la necesidad de mapear manualmente los endpoints o de usar Reflection de manera intensiva en tiempo de ejecución.
En su lugar, utiliza Source Generators para generar automáticamente el código de registro durante la compilación.

Cómo funciona

Para cada endpoint creado, el generador produce clases/partes de clases que llaman a:
MapGet, MapPost, MapPut, MapDelete, etc.

Esto reemplaza la necesidad de agregar manualmente todos los mapeos en Program.cs.

Ventajas:

• Registro en tiempo de compilación → evita errores en tiempo de ejecución.
• Program.cs más limpio → menor superficie de configuración manual.
• Compatibilidad AOT → elimina la dependencia de Reflection.
• Documentación integrada → los metadatos (tags, summary, produces) se generan junto con el mapeo.

Este modelo garantiza que las APIs creadas en Lino sean:

• Autodocumentadas
• Performantes
• Consistentes con la arquitectura CQRS del framework