minimal-apis（最小 API）

Minimal APIs Skill

Sorcha uses.NET 10 Minimal APIs exclusively—NEVER MVC controllers. All endpoints are organized via MapGroup() route grouping with extension methods in Endpoints/ folders. OpenAPI documentation uses Scalar (NOT Swagger).

Quick Start

Route Group with Authorization

// src/Services/Sorcha.Wallet.Service/Endpoints/WalletEndpoints.cs
public static IEndpointRouteBuilder MapWalletEndpoints(this IEndpointRouteBuilder app)
{
    var walletGroup = app.MapGroup("/api/v1/wallets")
        .WithTags("Wallets")
        .RequireAuthorization("CanManageWallets");

    walletGroup.MapPost("/", CreateWallet)
        .WithName("CreateWallet")
        .WithSummary("Create a new wallet")
        .WithDescription("Creates a new HD wallet with the specified algorithm");

    walletGroup.MapGet("/{address}", GetWallet)
        .WithName("GetWallet")
        .WithSummary("Get wallet by address");

    return app;
}

Endpoint Handler with DI

private static async Task<IResult> CreateWallet(
    [FromBody] CreateWalletRequest request,
    WalletManager walletManager,
    HttpContext context,
    ILogger<Program> logger,
    CancellationToken cancellationToken = default)
{
    try
    {
        var (wallet, mnemonic) = await walletManager.CreateWalletAsync(...);
        return Results.Created($"/api/v1/wallets/{wallet.Address}", response);
    }
    catch (ArgumentException ex)
    {
        return Results.BadRequest(new ProblemDetails { Title = "Invalid Request", Detail = ex.Message });
    }
}

Key Concepts

Common Patterns

TypedResults for Explicit Return Types

private static async Task<Results<Ok<TokenResponse>, UnauthorizedHttpResult, ValidationProblem>> Login(
    LoginRequest request,
    ITokenService tokenService)
{
    if (string.IsNullOrWhiteSpace(request.Email))
        return TypedResults.ValidationProblem(new Dictionary<string, string[]>
        {
            ["email"] = ["Email is required"]
        });

    var token = await tokenService.LoginAsync(request);
    if (token == null) return TypedResults.Unauthorized();

    return TypedResults.Ok(token);
}

Query Parameters with Defaults

walletGroup.MapGet("/{address}/addresses", ListAddresses);

private static async Task<IResult> ListAddresses(
    string address,                              // Route parameter
    [FromQuery] string? type = null,             // Optional filter
    [FromQuery] bool? used = null,               // Optional filter
    [FromQuery] int page = 1,                    // Default pagination
    [FromQuery] int pageSize = 50)

See Also

• patterns - Endpoint organization, error handling, caching
• workflows - Creating new endpoints, adding authorization

Related Skills

• See the aspire skill for service orchestration and configuration
• See the scalar skill for OpenAPI documentation UI
• See the jwt skill for authentication and authorization setup
• See the redis skill for output caching configuration
• See the signalr skill for real-time endpoint notifications

Documentation Resources

Fetch latest ASP.NET Core Minimal APIs documentation with Context7.

How to use Context7:

1. Use mcp__context7__resolve-library-id to search for "aspnetcore"
2. Prefer /websites/learn_microsoft_en-us_aspnet_core for official docs
3. Query with mcp__context7__query-docs

Library ID: /websites/learn_microsoft_en-us_aspnet_core

Recommended Queries:

• "minimal apis route groups"
• "minimal apis typed results"
• "minimal apis authorization"
• "minimal apis openapi documentation"