Développement d’API

Minimal APIs

Lino adopte le style Minimal API comme standard pour la génération d’endpoints, en privilégiant :

• Clarté – code concis, direct et expressif.
• Performance – réponses optimisées, sans surcharge inutile.

Fonctionnalités intégrées

TypedResults : garantissent des réponses fortement typées, aidant à la lisibilité et à la génération d’OpenAPI.

Versionnement des API : les endpoints peuvent évoluer sans rompre la compatibilité.

Documentation enrichie : des métadonnées configurables sont directement incorporées dans OpenAPI, incluant :

• WithTags → regroupe les endpoints en sections logiques dans OpenAPI.
• WithName → définit l’operationId de manière cohérente.
• WithSummary → décrit clairement l’objectif de l’endpoint.
• Produces(statusCode, schema) → spécifie les codes de statut et les contrats de réponse.
• MapToApiVersion → permet d’exposer différentes versions d’un même endpoint.

Requests et Responses

Record classes sont utilisées par défaut pour les Requests et Responses :

• Elles sont immuables (réduisant les effets secondaires et les bugs).
• Elles sont concises et faciles à lire.

Intégration avec CQRS :

• Les Requests reçues via les endpoints sont transformées en Commands ou Queries.
• Les résultats des Commands/Queries sont convertis en Responses, favorisant la cohérence architecturale.

Exemple simplifié :
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

Création de nouvelles API

Créer un endpoint avec la CLI de Lino est simple :

lino new api

L’assistant interactif demandera :

• Service – le service dans lequel l’API sera créée.
• Module – le module du service (le cas échéant).
• Entité – l’entité associée à l’endpoint.
• Nom de l’API – généralement aligné sur le verbe de l’opération (ex. : CreatePerson).
• Type d’opération – POST, PUT, PATCH, DELETE ou GET.
• Route – modèle de route (ex. : /people/{id}).

Exemple :

Lors de la création d’une API POST nommée CreatePerson associée à l’entité Person, la CLI génère automatiquement :

• Un endpoint avec le mapping HTTP.
• Des DTOs Request/Response.
• Des extensions pour l’intégration avec OpenAPI et le versionnement.

Structure générée :

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

Dans les projets disposant d’applications Web Blazor, Lino génère automatiquement les artefacts nécessaires à la consommation des API.
Cela inclut les contrats partagés (Request et Response/DTOs), l’interface du client et une implémentation standard pour les appels HTTP, permettant à Blazor de consommer les API de manière simple, typée et cohérente.

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

Enregistrement des Endpoints avec Source Generators

Lino supprime le besoin de mapper manuellement les endpoints ou d’utiliser intensivement Reflection à l’exécution.
À la place, il utilise les Source Generators pour générer automatiquement le code d’enregistrement lors de la compilation.

Comment ça fonctionne

Pour chaque endpoint créé, le générateur produit des classes/parties de classes qui appellent :
MapGet, MapPost, MapPut, MapDelete, etc.

Cela remplace la nécessité d’ajouter manuellement tous les mappages dans Program.cs.

Avantages :

• Enregistrement à la compilation → évite les erreurs à l’exécution.
• Program.cs épuré → surface de configuration manuelle réduite.
• Compatibilité AOT → élimine la dépendance à Reflection.
• Documentation intégrée → les métadonnées (tags, summary, produces) sont générées avec le mappage.

Ce modèle garantit que les API créées dans Lino sont :

• Auto-documentées
• Performantes
• Conformes à l’architecture CQRS du framework