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

Mit der CLI von Lino einen Endpoint zu erstellen ist ganz einfach:

lino new api

Der interaktive Assistent wird Folgendes abfragen:

• Service – der Service, in dem die API erstellt werden soll.
• Modul – das Modul des Services (falls zutreffend).
• Entität – die mit dem Endpoint verknüpfte Entität.
• API-Name – normalerweise auf das Verb der Operation abgestimmt (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 mit der Entität Person verknüpft ist, generiert die CLI automatisch:

• Endpoint mit HTTP-Mapping.
• Request/Response DTOs.
• Erweiterungen für die Integration mit OpenAPI und Versionierung.
• Typisierter HttpClient für die interne Nutzung durch andere Services.

Generierte Struktur:

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

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