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 très simple :

lino new api

L’assistant interactif vous 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 – le modèle de route (ex. : /people/{id}).

Exemple :

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

• Un endpoint avec un mapping HTTP.
• Des DTO de requête/réponse.
• Des extensions pour l’intégration avec OpenAPI et la gestion de version.
• Un HttpClient typé pour une utilisation interne par d’autres services.

Structure générée :

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

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