Developing APIs

Minimal APIs

Lino adopts the Minimal API style by default for endpoint generation, prioritizing:

• Clarity – concise, direct, and expressive code.
• Performance – optimized responses without unnecessary overhead.

Built-in Features

TypedResults: ensure strongly typed responses, aiding readability and OpenAPI generation.

API Versioning: endpoints can evolve without breaking compatibility.

Enriched Documentation: configurable metadata is directly incorporated into OpenAPI, including:

• WithTags → groups endpoints into logical sections in OpenAPI.
• WithName → consistently defines the operationId.
• WithSummary → clearly describes the endpoint’s purpose.
• Produces(statusCode, schema) → specifies status codes and response contracts.
• MapToApiVersion → allows exposing different versions of the same endpoint.

Requests and Responses

Record classes are used by default for Requests and Responses:

• They are immutable (reducing side effects and bugs).
• They are concise and easy to read.

Integration with CQRS:

• Requests received via endpoints are transformed into Commands or Queries.
• Results from Commands/Queries are converted into Responses, promoting architectural consistency.

Simplified example:
public record CreatePersonRequest(string Name, int Age);
public record CreatePersonResponse(Guid Id, string Name, int Age);

Creating New APIs

Creating an endpoint using the Lino CLI is simple:

lino new api

The interactive wizard will ask for:

• Service – the service where the API will be created.
• Module – the service module (when applicable).
• Entity – the entity associated with the endpoint.
• API Name – usually aligned with the operation verb (e.g., CreatePerson).
• Operation Type – POST, PUT, PATCH, DELETE, or GET.
• Route – route pattern (e.g., /people/{id}).

Example:

When creating a POST API named CreatePerson associated with the Person entity, the CLI automatically generates:

• Endpoint with HTTP mapping.
• Request/Response DTOs.
• Extensions for OpenAPI integration and versioning.

Generated structure:

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

In projects that include Blazor Web applications, Lino automatically generates the necessary artifacts for API consumption.
This includes shared contracts (Request and Response/DTOs), the client interface, and a default implementation for HTTP calls, allowing Blazor to consume the APIs in a simple, strongly typed, and consistent way.

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

Endpoint Registration with Source Generators

Lino eliminates the need for manual endpoint mapping or heavy use of Reflection at runtime.
Instead, it uses Source Generators to automatically produce registration code during compilation.

How it works

For each created endpoint, the generator produces classes/partial classes that call:
MapGet, MapPost, MapPut, MapDelete, etc.

This replaces the need to manually add all mappings in Program.cs.

Advantages:

• Compile-time registration → avoids runtime errors.
• Lean Program.cs → smaller surface for manual configuration.
• AOT compatibility → removes Reflection dependency.
• Integrated documentation → metadata (tags, summary, produces) is generated along with the mapping.

This model ensures that APIs created in Lino are:

• Self-documented
• High-performance
• Consistent with the framework’s CQRS architecture