Sviluppo di API

Minimal APIs

Lino adotta lo stile Minimal API come impostazione predefinita per la generazione di endpoint, privilegiando:

• Chiarezza – codice conciso, diretto ed espressivo.
• Performance – risposte ottimizzate senza overhead inutile.

Funzionalità integrate

TypedResults: garantiscono risposte fortemente tipizzate, migliorando la leggibilità e la generazione di OpenAPI.

Versionamento delle API: gli endpoint possono evolvere senza rompere la compatibilità.

Documentazione arricchita: i metadati configurabili sono incorporati direttamente in OpenAPI, includendo:

• WithTags → raggruppa gli endpoint in sezioni logiche in OpenAPI.
• WithName → definisce l’operationId in modo coerente.
• WithSummary → descrive chiaramente lo scopo dell’endpoint.
• Produces(statusCode, schema) → specifica codici di stato e contratti di risposta.
• MapToApiVersion → consente di esporre diverse versioni dello stesso endpoint.

Requests e Responses

Record classes sono utilizzate per Requests e Responses di default:

• Sono immutabili (riducendo effetti collaterali e bug).
• Sono concise e di facile lettura.

Integrazione con CQRS:

• Le Requests ricevute tramite endpoint vengono trasformate in Commands o Queries.
• I risultati di Commands/Queries vengono convertiti in Responses, promuovendo coerenza architetturale.

Esempio semplificato:
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

Creazione di nuove API

Creare un endpoint con la CLI di Lino è molto semplice:

lino new api

La procedura guidata interattiva richiederà:

• Servizio – il servizio in cui verrà creata l’API.
• Modulo – il modulo del servizio (se applicabile).
• Entità – l’entità associata all’endpoint.
• Nome dell’API – solitamente allineato al verbo dell’operazione (es.: CreatePerson).
• Tipo di operazione – POST, PUT, PATCH, DELETE o GET.
• Rotta – schema di rotta (es.: /people/{id}).

Esempio:

Quando si crea una API POST chiamata CreatePerson associata all’entità Person, la CLI genera automaticamente:

• Endpoint con mappatura HTTP.
• Request/Response DTO.
• Estensioni per l’integrazione con OpenAPI e il versionamento.
• HttpClient tipizzato per l’uso interno da parte di altri servizi.

Struttura generata:

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

Registrazione degli Endpoint con Source Generators

Lino elimina la necessità di mappare manualmente gli endpoint o di usare intensivamente Reflection a runtime.
Invece, utilizza i Source Generators per generare automaticamente il codice di registrazione durante la compilazione.

Come funziona

Per ogni endpoint creato, il generator crea classi/parziali che chiamano:
MapGet, MapPost, MapPut, MapDelete, ecc.

Questo sostituisce la necessità di aggiungere manualmente tutte le mappature in Program.cs.

Vantaggi:

• Registrazione a tempo di compilazione → evita errori a runtime.
• Program.cs snello → minore superficie di configurazione manuale.
• Compatibilità AOT → elimina la dipendenza da Reflection.
• Documentazione integrata → i metadati (tags, summary, produces) vengono generati insieme alla mappatura.

Questo modello garantisce che le API create in Lino siano:

• Auto-documentate
• Performanti
• Consistenti con l’architettura CQRS del framework