API-Entwicklung

Minimal APIs

Lino verwendet standardmäßig den Minimal API-Stil zur Erstellung von Endpunkten und legt dabei den Fokus auf:

• Klarheit – schlanker, direkter und ausdrucksstarker Code.
• Performance – optimierte Antworten ohne unnötigen Overhead.

Integrierte Funktionen

TypedResults: sorgen für stark typisierte Antworten und unterstützen die Lesbarkeit sowie die OpenAPI-Generierung.

API-Versionierung: Endpunkte können weiterentwickelt werden, ohne die Kompatibilität zu brechen.

Erweiterte Dokumentation: konfigurierbare Metadaten werden direkt in OpenAPI eingebunden, einschließlich:

• WithTags → gruppiert Endpunkte in logische Abschnitte in OpenAPI.
• WithName → definiert operationId konsistent.
• WithSummary → beschreibt den Zweck des Endpunkts klar.
• Produces(statusCode, schema) → spezifiziert Statuscodes und Antwortverträge.
• MapToApiVersion → ermöglicht das Veröffentlichen verschiedener Versionen desselben Endpunkts.

Requests und Responses

Record classes werden standardmäßig für Requests und Responses verwendet:

• Sie sind unveränderlich (reduziert Nebenwirkungen und Fehler).
• Sie sind prägnant und leicht lesbar.

Integration mit CQRS:

• Requests, die über Endpunkte empfangen werden, werden in Commands oder Queries umgewandelt.
• Die Ergebnisse von Commands/Queries werden in Responses umgewandelt, was die architektonische Konsistenz fördert.

Vereinfachtes Beispiel:
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

Erstellen neuer APIs

Das Erstellen eines Endpoints mit der Lino-CLI ist einfach:

lino new api

Der interaktive Assistent fragt nach:

• Service – der Service, in dem die API erstellt wird.
• Modul – das Modul des Services (falls zutreffend).
• Entität – die dem Endpoint zugeordnete Entität.
• API-Name – in der Regel am Operationsverb ausgerichtet (z. B. CreatePerson).
• Operationstyp – POST, PUT, PATCH, DELETE oder GET.
• Route – Routenmuster (z. B. /people/{id}).

Beispiel:

Beim Erstellen einer POST-API mit dem Namen CreatePerson, die der Entität Person zugeordnet ist, generiert die CLI automatisch:

• Endpoint mit HTTP-Zuordnung.
• Request-/Response-DTOs.
• Erweiterungen für OpenAPI-Integration und Versionierung.

Generierte Struktur:

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

In Projekten mit hinzugefügten Blazor-Webanwendungen generiert Lino automatisch die erforderlichen Artefakte für den API-Verbrauch.
Dazu gehören gemeinsam genutzte Verträge (Request- und Response-/DTOs), die Client-Schnittstelle sowie eine Standardimplementierung für HTTP-Aufrufe, sodass Blazor die APIs einfach, typisiert und konsistent konsumieren kann.

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

Registrierung von Endpunkten mit Source Generators

Lino beseitigt die Notwendigkeit, Endpunkte manuell zu mappen oder Reflection zur Laufzeit intensiv zu nutzen.
Stattdessen werden Source Generators verwendet, um den Registrierungscode automatisch während der Kompilierung zu erzeugen.

Wie es funktioniert

Für jeden erstellten Endpunkt erzeugt der Generator Klassen/Teilklassen, die aufrufen:
MapGet, MapPost, MapPut, MapDelete usw.

Dies ersetzt die Notwendigkeit, alle Mappings manuell in Program.cs hinzuzufügen.

Vorteile:

• Registrierung zur Kompilierzeit → verhindert Laufzeitfehler.
• Schlankes Program.cs → geringere manuelle Konfigurationsoberfläche.
• AOT-Kompatibilität → beseitigt die Abhängigkeit von Reflection.
• Integrierte Dokumentation → Metadaten (tags, summary, produces) werden zusammen mit dem Mapping generiert.

Dieses Modell stellt sicher, dass die in Lino erstellten APIs:

• Automatisch dokumentiert sind
• Leistungsfähig sind
• Mit der CQRS-Architektur des Frameworks konsistent sind