Developing APIs

Minimal APIs on Lino

Lino adopts ASP.NET Core Minimal APIs as a standard for generating endpoints, because they keep the code direct, explicit and performant without breaking the boundaries of Clean Architecture.

In current Lino projects, generated endpoints are Minimal API classes that implement IEndpoint. Each endpoint exposes a static method MapEndpoint(IEndpointRouteBuilder app) and a handler method that uses ISender to dispatch the generated command or query to the Application layer.

Generated main parts

• *Endpoint.cs: maps the HTTP method, route, metadata, authorization, tenant requirement, rate limiting and version.
• *Request.cs: represents input coming from body, query string, route parameters or form data.
• *Extensions.cs: converts request to command/query and converts the application result to an HTTP response.
• *Response.cs: defines the strongly typed contract returned by the endpoint and typed clients.

Built-in features

Lino uses TypedResults and Results<...> so that success and error responses are explicit in the code and appear correctly in OpenAPI. Faults coming from the Application layer are converted to ProblemDetails through result.MapToProblemDetails().

• WithTags: Groups endpoints by module, entity, or feature in OpenAPI and Scalar.
• WithName: Sets a consistent operationId when applicable.
• WithSummary: clearly describes the purpose of the endpoint.
• Produces(statusCode, schema): specifies status codes and response contracts.
• MapToApiVersion(1, 0): associates the endpoint with the API version.
• RequirePermission, RequireAuthorization, AllowAnonymous and RequireTenant: apply security according to the project options.
• Rate limiting at the group or endpoint level, using authenticated or anonymous policies depending on the configuration.

Requests and Responses

By default, Lino uses records for requests and responses. They are concise, immutable by default, and work well as explicit contracts between API, typed clients, and external consumers.

• Requests received via endpoint are transformed into Commands or Queries.
• Results of Commands or Queries are converted into Responses.
• Domain entities should not be directly exposed as an HTTP contract.

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

Creating new APIs

Create APIs with the CLI when the domain model and use case are already clear enough to be exposed by HTTP. APIs connect commands and queries to the presentation layer via Minimal APIs, contracts, typed responses and documentation metadata.

lino api new
lino api new --name <ApiName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino api list --service <ServiceName> --module <ModuleName> --entity <EntityName>

The interactive wizard will prompt:

• Service: service where the API will be created.
• Module: service module, when applicable.
• Entity or enumeration: domain element associated with the endpoint.
• API name: normally aligned with the verb of the operation, such as CreatePerson.
• Type of operation: GET, POST, PUT, PATCH, DELETE, upload, download or options endpoint.
• Route: route pattern, like /people/{id:guid}.
• Properties: request and response fields that must actually cross the HTTP boundary.

What the wizard can configure

• GET: single result, list, paged list and options/select scenarios.
• POST: creation and business actions, including command type and selected properties.
• PUT and PATCH: complete or partial update.
• DELETE: removal mapped to delete commands.
• Upload: endpoints with IFormFile and DisableAntiforgery() when necessary.
• Download:returning endpoints FileStreamHttpResult; authenticated projects can generate a token endpoint for secure file access.
• Enumerations: endpoints that expose valid options per generated query and response.

Recommended flow

1. Create or review the entity, commands, and queries that represent the use case.
2. Run lino api new and select correct service, module and entity.
3. Choose the type of operation by use case, not just by the desired HTTP verb.
4. Define stable route, using constraints like {id:int} or {id:guid} when appropriate.
5. Select only properties that must cross the HTTP boundary.
6. Define authorization, permission, tenant requirement, rate limiting and expected status codes.
7. Run the build and inspect Scalar/OpenAPI to confirm route, summary, version, security and responses produced.

Example: CreatePerson

When creating a API POST call CreatePerson, associated with the entity Person, CLI generates endpoint, request/response contracts, mapping extensions, OpenAPI metadata and integration with the corresponding command.

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Api/
                └── Endpoints/
                    └── People/
                        └── CreatePerson/
                            ├── CreatePersonEndpoint.cs
                            ├── CreatePersonExtensions.cs
                            ├── CreatePersonRequest.cs
                            └── CreatePersonResponse.cs

Contracts and typed clients

When the project has a Web App Blazor, Lino also generates artifacts for typed consumption of APIs: shared contracts, client interface and HTTP implementation. This allows Blazor to consume endpoints in a simple, consistent, and strongly typed way.

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            ├── Api.Contracts/
            │   └── Features/
            │       └── People/
            │           ├── CreatePerson/
            │           │   ├── CreatePersonRequest.cs
            │           │   └── CreatePersonResponse.cs
            │           └── IPersonApiClient.cs
            └── Api.Client/
                └── Features/
                    └── PersonApiClient.cs

The client interface is registered for dependency injection, and the implementation uses HttpClientProvider with Tolitech's HTTP helpers to call the generated API in a strongly typed way.

Checklist before publishing

• Use GET for reading, POST for creation/actions, PUT/PATCH for change and DELETE for removal when it makes sense.
• Do not expose domain entities directly as an external contract.
• Document validation, conflict, not found, and access denied errors.
• Use api list to avoid duplicate routes or competing endpoints for the same use case.

Endpoint Registration with Source Generators

Lino avoids manually mapping large files using source generators. Instead of listing endpoints one by one in Program.cs, registration is produced during compilation.

Generated endpoint classes implement IEndpoint from Tolitech.MinimalApis.Generators.Abstractions. The endpoint group calls MapEndpointsGenerated(), produced by Tolitech.MinimalApis.Generators, and new endpoints are registered by generated code.

Why this matters

• Less manual wiring: Developers don't need to remember to map each endpoint manually.
• Compile-time consistency: endpoints follow the same structure and are discovered by generated code.
• Cleaner startup: Program.cs delegates setup for configuring services, middleware and extension methods.
• AOT compatibility: reduces dependency on reflection at runtime.
• Consistent OpenAPI: tags, summaries, status codes and version are generated with the endpoint.
• Architectural alignment: HTTP is in API, orchestration goes through MediatR, and contracts can be shared with clients.

Flow at runtime

1. Program.cs builds the application and calls the extension from the service or module endpoints.
2. The extension creates the API version set and the endpoint group, applies authorization/rate limiting and calls MapEndpointsGenerated().
3. The generated mapper calls the method MapEndpoint of each endpoint.
4. Each endpoint maps route, OpenAPI metadata, permission, tenant requirement and handler.
5. The handler receives HTTP input, converts it to command/query, sends it to MediatR and returns a typed result.

Error definitions

Error definitions standardize known domain and application faults. They help APIs, handlers, logs, and frontends handle predictable problems without relying on stray messages, duplicate strings, or ad hoc decisions at each endpoint.

lino error-definition new --name <ErrorDefinitionName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino error-definition list --service <ServiceName> --module <ModuleName> --entity <EntityName>

In generated APIs, expected failures returned by commands and queries must be converted to ProblemDetails with status code, error code and secure message. The server may record detailed technical logs, but the HTTP response must remain consistent, secure, and localizable.

Good practices

• Create error definitions for expected and reusable failures.
• Avoid returning technical exceptions or infrastructure details to the client.
• Maintain stable error codes so frontend, typed clients, and tests can react safely.
• Document in OpenAPI the status codes that the endpoint can produce.
• Use server-side logs for diagnostic details and secure messages in the public response.