Software Engineer Encyclopedia
0%
Domain 03 · Backend Engineering & Web Development · Topic 3.7

Minimal APIs في ASP.NET Core

Minimal APIs

Endpoint mapping وroute groups وparameter binding وTypedResults وDI وvalidation وauthorization وendpoint filters وOpenAPI وتنظيم APIs الكبيرة.

  • Intermediate
  • ~13 min read
  • 10 sections
  • 15 code examples
  • 2 diagrams
  • 3 questions
  • Priority L2 · Important
  • .NET 10 LTS · ASP.NET Core 10 · C# 14

المتطلبات قبل ما تبدأ

C# و.NET (المجال 02) والـ HTTP/Networking (درس 1.2).

مستوى التعمق المطلوب

PRACTICALUnderstand the approach without needing to master every advanced feature.

01

Endpoint Mapping و Route Groups

MapGet, MapPost, MapGroup
Practical

Minimal APIs تسمح بتعريف HTTP endpoints مباشرة على WebApplication أو IEndpointRouteBuilder من غير Controller class. كلمة Minimal معناها أقل ceremony، مش إن التطبيق لازم يكون ملف واحد أو بدون architecture.

C#Program.cs — grouped endpoints
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddScoped<IProductService, ProductService>();
var app = builder.Build();

var products = app.MapGroup("/api/products")
    .WithTags("Products");

products.MapGet("/{id:int}", async (
    int id, IProductService service, CancellationToken token) =>
{
    var product = await service.FindAsync(id, token);
    return product is null
        ? Results.NotFound()
        : Results.Ok(product);
});

app.Run();

public partial class Program { }

MapGroup يشارك prefix والـ metadata والـ filters/auth policy بين endpoints. تقدر تعمل groups nested؛ ده يساعد في versioning أو admin endpoints. لا تجعل group boundaries تعكس كل folders؛ خليها تعكس contract/security boundaries.

Route Groups كحدود Feature و Security

Route group مش مجرد prefix تقليل كتابة. تقدر تطبق tags، authorization، filters، conventions، rate limiting metadata، و OpenAPI metadata على المجموعة. استخدم nested groups لما يكون عندك boundary منطقي مثل /api/v1/admin. خلي authorization policies في مكان واضح، وتأكد إن endpoint لا يعمل AllowAnonymous بلا قصد داخل group محمية.

C#Nested groups with inherited policy
var api = app.MapGroup("/api/v1").WithTags("API v1");
var admin = api.MapGroup("/admin")
    .RequireAuthorization("Administrators");

admin.MapGet("/audit", GetAuditEntries);
admin.MapPost("/reindex", StartReindex)
    .RequireRateLimiting("admin-commands");

اختبر metadata الفعلية على endpoints، لأن inherited conventions و explicit overrides ممكن تؤثر في النتيجة النهائية. لا تعتمد على شكل الكود وحده لإثبات authorization.

Endpoint Conventions و Metadata

Endpoint conventions تسمح بتطبيق tags و OpenAPI metadata و filters و auth/rate policies على groups. استخدمها لتقليل duplication، لكن اجعل final endpoint metadata واضحة عند review. لا تجعل convention مخفية تضيف authorization أو تغير response behavior بشكل غير متوقع من غير tests/documentation.

Minimal API Request Flow

HTTP RequestMiddlewareEndpoint RoutingHandlerBindingFilters / AuthTyped Result
Minimal API تقلل ceremony لكنها تمر بنفس ASP.NET Core host and middleware foundation.

الاختلاف الأساسي عن MVC هو شكل endpoint declaration و handler invocation، مش اختفاء middleware أو DI أو HTTP semantics. لذلك خبرتك في pipeline و authorization و validation ما زالت مطلوبة. الـ handler يجب أن يبقى thin، والـ route groups تنظم metadata والـ policies، والـ application service تحمل use case.

02

Parameter Binding و Typed Results

Where values come from and what is returned
Deep dive

Minimal APIs تستنتج binding source حسب نوع parameter: route/query values للـ simple types، services من DI، و body للأنواع المركبة في حالات محددة. صرّح بـ [FromRoute] و [FromQuery] و [FromBody] و [FromServices] عندما يزيد الوضوح، خصوصاً في public contract.

C#Typed results for documented response alternatives
products.MapGet("/{id:int}", async Task<Results<Ok<ProductResponse>, NotFound>> (
    [FromRoute] int id,
    [FromServices] IProductService service,
    CancellationToken token) =>
{
    var product = await service.FindAsync(id, token);
    return product is null
        ? TypedResults.NotFound()
        : TypedResults.Ok(product);
});

Typed Results تجعل response alternatives صريحة وتساعد OpenAPI metadata. IResult أكثر مرونة لكنه قد يخفي schema/status alternatives من التحليل static. لا تخلط return types عشوائياً؛ حدد response contract.

Parameter Binding Inference بالتفصيل

Minimal API framework يستنتج مصدر parameter من نوعه وسياق endpoint. Simple types غالباً من route أو query؛ registered service من DI؛ complex parameter قد يأتي من body؛ و HttpContext و CancellationToken أنواع خاصة. لو signature فيها parameter مصدره غير واضح، استخدم attributes مثل [FromRoute] و [FromQuery] و [FromBody] و [FromServices]. ده يجعل العقد مقروءاً ويقلل أخطاء inference.

Body عادة يُقرأ مرة واحدة. لا تضف أكثر من body parameter مستقل. لو تحتاج عدة values، اجمعها في request DTO. Query parameters تحتاج parsing و validation؛ لا تعتمد على أن int pageSize وحده يضمن الحد الأقصى أو المعنى التجاري الصحيح.

C#Explicit binding and cancellation
app.MapGet("/api/orders/{orderId:int}", async (
    [FromRoute] int orderId,
    [FromQuery] bool includeLines,
    [FromHeader(Name = "X-Api-Client")] string? client,
    [FromServices] IOrderQuery query,
    CancellationToken cancellationToken) =>
{
    var order = await query.FindAsync(orderId, includeLines, cancellationToken);
    return order is null ? Results.NotFound() : Results.Ok(order);
});

Typed Results و OpenAPI Response Metadata

IResult abstraction تسمح endpoint يرجع HTTP result، لكنها لا تعطي compiler دائماً معرفة بكل response types. TypedResults ترجع concrete result types، ويمكن جمع alternatives في Results<T1,T2>. ده يحسن compile-time checking و OpenAPI metadata. لو عندك endpoint يرجع 200 أو 404 أو 409، وثّق الثلاثة ولا تكتفِ بتوثيق success فقط.

C#Explicit response union
static async Task<Results<Ok<ProductResponse>, NotFound, Conflict<ProblemDetails>>> Get(
    int id, IProductService service, CancellationToken token)
{
    var result = await service.GetAsync(id, token);
    return result switch
    {
        ProductFound found => TypedResults.Ok(found.Product),
        ProductMissing => TypedResults.NotFound(),
        ProductConflict conflict => TypedResults.Conflict(
            new ProblemDetails { Title = conflict.Message }),
        _ => TypedResults.NotFound()
    };
}

الـ union هنا مثال توضيحي؛ صمّم result types الفعلية حسب application contract. لا تترك fallback غير متوقع يحول كل unknown state إلى 404 من غير logging/diagnostics.

TypedResults و Validation Errors

في Minimal APIs، endpoint handler ممكن يرجع IResult أو typed result أو result union. اختار أسلوباً ثابتاً داخل feature. Validation errors لازم تكون Problem Details/ValidationProblemDetails بشكل consistent، مع نفس field keys التي يستخدمها client. لا ترجع plain string في endpoint و Problem Details في endpoint آخر لنفس فئة الأخطاء.

Endpoint filters مناسبة لقواعد مشتركة مرتبطة بالـ handler arguments، لكن لا تحول filter إلى global validator لكل DTO من غير contract. validator منفصل يسهل unit testing، والـ endpoint يترجم النتيجة إلى HTTP.

Binding Edge Cases و Request Size

الـ endpoint signature جزء من API design. لو عندك body DTO و services و CancellationToken، افهم inference حتى لا يتعامل framework مع parameter كمصدر خاطئ. استخدم attributes صريحة عند الحاجة. لا تقبل HttpRequest ثم تعمل parsing يدوي لكل شيء إلا إذا عندك سبب streaming/protocol خاص؛ ده يفقدك conveniences و validation.

ضع request size limits، query length limits، page size caps، و collection max counts. Validation لا تقتصر على business values؛ resource limits تمنع memory/CPU abuse. في file upload، استخدم multipart limits و streaming pattern بدل body DTO ضخم.

03

DI و Validation

Thin handlers and validated requests
Practical

Services المسجلة في DI يمكن حقنها كـ handler parameters. ده مناسب للـ endpoint لأنه لا يحتاج constructor. تجنب إدخال business logic كبير داخل lambda؛ انقل use case إلى service/handler class. Validation options تختلف بين controller model validation و Minimal API validation; افحص ‎.NET 10 behavior الحالي و FluentValidation integration إذا احتجت قواعد complex/async.

C#Small endpoint with explicit validation
public sealed record CreateProductRequest(string Name, decimal Price);

products.MapPost("/", async (
    CreateProductRequest request,
    IProductService service,
    CancellationToken token) =>
{
    if (string.IsNullOrWhiteSpace(request.Name) || request.Name.Length > 120)
        return Results.ValidationProblem(new Dictionary<string, string[]>
        {
            ["name"] = ["Name is required and must be <= 120 characters."]
        });
    if (request.Price <= 0)
        return Results.ValidationProblem(new Dictionary<string, string[]>
        {
            ["price"] = ["Price must be greater than zero."]
        });

    var created = await service.CreateAsync(request, token);
    return Results.Created($"/api/products/{created.Id}", created);
});

هذا validation illustrative؛ لقواعد أكبر، انقلها إلى validator قابل للاختبار ولا تكرر نفس rules في endpoints متعددة. Database constraints تظل ضرورية للتفرد والتزامن.

Binding Inference و Auth Decisions

من أكثر الأخطاء شيوعاً الاعتقاد أن كل parameter معقد يأتي من DI. Framework يطبق conventions بناءً على registered services و route metadata وأنواع parameters؛ لو غامض، صرّح binding source. Route parameter constraint مثل {id:int} يحدد route match وليس وجود record في DB. Body binding غالباً يقرأ body مرة واحدة، فلا تجعل signature تطلب أكثر من body object. استخدم CancellationToken parameter لتمرير cancellation.

Authorization على group يورّث metadata للأعضاء؛ endpoint يمكن أن يضيف policy أكثر تحديداً. لا تخلط authentication مع role check، واستخدم resource-based authorization عندما القرار يعتمد على owner/tenant/object state وليس role عام فقط.

C#A group with policy and explicit binding
var tenantApi = app.MapGroup("/api/tenant")
    .RequireAuthorization("TenantMember");

tenantApi.MapGet("/{tenantId:int}/products", async (
    [FromRoute] int tenantId,
    [FromQuery] int pageSize,
    IProductService service,
    ClaimsPrincipal user,
    CancellationToken token) =>
{
    if (pageSize is < 1 or > 100) return Results.BadRequest();
    var result = await service.ListForTenantAsync(tenantId, user, pageSize, token);
    return Results.Ok(result);
});

Validation و Versioning و Organizing Features

للـ validation البسيطة ممكن تستخدم guards واضحة أو validation support في framework وفق ‎.NET version. لقواعد معقدة، اجعل validator منفصل واختبره. اجمع endpoints حسب feature في extension methods أو route modules. Versioning يمكن تطبيقه على groups مع OpenAPI document لكل version حسب package/configuration المستخدمة؛ لا تضع كل routes في Program.cs مع شروط متكررة.

لا تجعل Minimal APIs تعني عدم وجود controllers أو services. اختيار الأسلوب يعتمد على حجم الـ API، الفريق، conventions، metadata، model binding needs، filters، ووجود legacy MVC. الهدف تقليل ceremony مع الحفاظ على structure واضح.

04

Authorization و Endpoint Filters و OpenAPI

Endpoint metadata and cross-cutting behavior
Practical
C#Authorization and filter registration
var admin = app.MapGroup("/api/admin")
    .RequireAuthorization("Administrators");

admin.AddEndpointFilter(async (context, next) =>
{
    var started = Stopwatch.GetTimestamp();
    var result = await next(context);
    var elapsed = Stopwatch.GetElapsedTime(started);
    context.HttpContext.Response.Headers["X-Endpoint-Duration-Ms"] =
        elapsed.TotalMilliseconds.ToString("F1", CultureInfo.InvariantCulture);
    return result;
});

admin.MapGet("/metrics", () => TypedResults.Ok(new { status = "restricted" }))
    .WithName("GetAdminMetrics")
    .WithSummary("Returns admin metrics")
    .Produces(StatusCodes.Status200OK);

Endpoint filters تحيط handler invocation وتستطيع فحص arguments أو تعديل result. Authorization تعتمد على endpoint metadata/policies مثل controller endpoints. OpenAPI metadata توثق operation، لكنها لا تمنح protection؛ لا تخلط HideFromDescription مع authorization.

Endpoint Filters: قبل وبعد Handler

Endpoint filter يشبه middleware لكن نطاقه endpoint execution وليس كل HTTP pipeline. يقدر يشوف arguments بعد binding، يعمل validation أو timing، ثم يستدعي next أو يرجع result مباشرة. استخدمه للسلوك المشترك بين endpoints، لكن لا تكرر model validation أو authorization الموجودة بالفعل في framework.

C#Reusable endpoint filter
public sealed class RequestTimingFilter(ILogger<RequestTimingFilter> logger)
    : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext context,
        EndpointFilterDelegate next)
    {
        var started = Stopwatch.GetTimestamp();
        try
        {
            return await next(context);
        }
        finally
        {
            logger.LogInformation("Endpoint {Endpoint} took {ElapsedMs} ms",
                context.HttpContext.GetEndpoint()?.DisplayName,
                Stopwatch.GetElapsedTime(started).TotalMilliseconds);
        }
    }
}

لو filter هتعمل database access، راجع lifetime والـ async/cancellation، وتأكد أنها لا تنفذ query لكل endpoint بلا داعٍ. Endpoint filters لا تستبدل middleware العامة ولا resource authorization.

Error Mapping في Minimal APIs

Minimal API endpoint يمكن أن ترجع Results.Problem أو Results.ValidationProblem أو typed results. المهم إن كل feature تستخدم contract موحد. لو application service ترجع Result، اعمل mapper مركزي من application error إلى HTTP. لا تكرر switch statement كبير في كل endpoint.

يمكن إضافة endpoint filter لقياس latency أو validation عامة، لكن global exception handler/Problem Details يظل boundary مناسباً للأخطاء غير المتوقعة. لا تجعل exception تتسرب وتتحول إلى HTML developer page في production.

Problem Details و OpenAPI في Minimal APIs

Minimal API endpoints تحتاج نفس مستوى contract discipline الموجود في controllers. استخدم typed results أو .Produces<T>/.ProducesProblem metadata وفق الحاجة. وثّق status code لكل outcome، وخلّي validation/exception handling consistent. OpenAPI metadata لا تحمي endpoint؛ authorization policy هي التي تحميها.

لو route group تمثل API version، اربط كل endpoints بالـ document المناسب وتأكد من عدم ظهور internal endpoints في public document. اختبر document generated مع endpoint integration tests حتى لا تتباعد الوثيقة عن runtime.

05

تنظيم Minimal APIs عندما تكبر

Route modules without giant Program.cs
Deep dive

ابدأ بملف Program صغير و extension methods أو endpoint modules لكل feature. حافظ على endpoint handler رفيعاً؛ request validation و authorization في boundary، business behavior في application services، persistence وراء data abstraction. لا تصنع abstraction عامة معقدة قبل وجود تكرار حقيقي.

C#ProductsEndpoints.cs — route module
public static class ProductsEndpoints
{
    public static RouteGroupBuilder MapProducts(this IEndpointRouteBuilder routes)
    {
        var group = routes.MapGroup("/api/products").WithTags("Products");
        group.MapGet("/{id:int}", GetById);
        return group;
    }

    private static async Task<Results<Ok<ProductResponse>, NotFound>> GetById(
        int id, IProductService service, CancellationToken token)
    {
        var result = await service.FindAsync(id, token);
        return result is null ? TypedResults.NotFound() : TypedResults.Ok(result);
    }
}

الـ extension method يضيف endpoints فقط؛ التسجيل في Program يبقى واضحاً عبر app.MapProducts(). هذا يمنح separation من غير framework جديد.

Minimal API Design Checklist

  • Route يعكس resource/operation semantics بوضوح.
  • Binding sources مفهومة أو صريحة.
  • Handler رفيع ويستدعي application service.
  • CancellationToken يصل إلى I/O.
  • Validation و authorization منفصلان وواضحان.
  • Response alternatives typed/documented.
  • Route groups تحمل metadata المشتركة فقط.
  • OpenAPI يعكس الواقع.
  • Integration tests تغطي 2xx و4xx و auth و binding.

Minimal API قوية لأنها built-in وتقلل ceremony، لكن لا تسمح لصغر syntax أن يخفي architecture. كل ما endpoint lambda تكبر، انقل behavior إلى named handler أو feature module.

Organizing a Larger Minimal API Application

تطبيق Minimal API كبير يحتاج structure مثل أي application: Program.cs للـ host/configuration/composition root، features modules لتسجيل routes، Application services/use cases، domain rules، infrastructure implementations. لا تجعل كل module يبني service provider أو ينشئ DbContext بنفسه. registration يظل في composition root أو extension methods واضحة.

C#Feature module registration
public static class ProductModule
{
    public static IServiceCollection AddProductFeature(
        this IServiceCollection services)
    {
        services.AddScoped<IProductService, ProductService>();
        return services;
    }

    public static IEndpointRouteBuilder MapProductFeature(
        this IEndpointRouteBuilder endpoints)
    {
        var group = endpoints.MapGroup("/api/products")
            .WithTags("Products");

        group.MapGet("/{id:int}", GetById);
        group.MapPost("/", Create);
        return endpoints;
    }
}

خلي endpoint methods named لما logic يزيد عن guard + service call. تجنب static global state. اعمل unit tests للـ use cases و integration tests للـ HTTP contract. لو المشروع محتاج MVC features كثيرة، لا ترفض Controllers لمجرد أنك بدأت Minimal APIs.

متى تختار Minimal APIs؟

Minimal APIs ممتازة لخدمات صغيرة/متوسطة، microservices، endpoints واضحة، و applications تريد أقل ceremony. Controllers مناسبة لما تحتاج MVC conventions واسعة، filters/actions organization، أو فريق مرتاح للنمط. الاتنين مبنيين على ASP.NET Core endpoint routing و DI و middleware؛ لا تجعل الاختيار يحدد architecture بالكامل.

06

اختبار Endpoint Modules

Test behavior through HTTP
Practical

اختبار handler service وحده لا يثبت صحة route, binding, JSON, filters, auth metadata أو middleware. استخدم WebApplicationFactory لطلب endpoint عبر HttpClient، واستبدل فقط external dependency المعينة في الاختبار. اختبر 200/201 و validation failure و404 و401/403، وتأكد من schema/status documentation.

Testing و OpenAPI و Versioned Groups

كل endpoint module يمكن اختباره من HTTP عبر WebApplicationFactory، ويمكن اختبار application service منفصلاً. اختبر route binding، malformed query، body validation، status codes، authorization، و OpenAPI operation schema. Minimal APIs لا تعني التخلي عن integration tests.

مع كبر التطبيق، خزن كل feature في module مستقل، واجعل التسجيل في Program واضحاً: app.MapProducts() و app.MapOrders(). لا تضع business rules في lambdas الطويلة. لا تصنع generic endpoint framework خاص بك قبل ما تتأكد أن عندك duplication حقيقي.

Testing Minimal API Contract

Integration tests عبر WebApplicationFactory تستطيع تشغيل minimal app من غير network port حقيقي. تأكد من إتاحة Program للـ test assembly باستخدام public partial class Program في top-level setup عند الحاجة. اختبر invalid route/query parsing، body validation، cancellation، response schema، authorization metadata، و OpenAPI output.

لا تجعل tests تعتمد على in-memory database إذا كان الهدف إثبات SQL query behavior أو transaction semantics. استبدل service في endpoint tests عندما تختبر HTTP contract، واستخدم database integration tests منفصلة عندما تختبر persistence.

07

Validation المدمج في Minimal APIs (‎.NET 10)

Built-in validation
Deep dive

قبل ‎.NET 10، Minimal APIs ما كانش فيها validation تلقائي زي [ApiController]، فالناس كانت بتكتب endpoint filters أو تستخدم FluentValidation يدويًا. من ‎.NET 10 فيه دعم مدمج مبني على Microsoft.Extensions.Validation: بتسجل AddValidation() وبتستخدم DataAnnotations على الـ request types، والـ validation بيتعمل عبر source generator (مناسب للـ AOT).

C#Program.cs + endpoint (.NET 10)
builder.Services.AddValidation();         // enables validation for minimal API parameters (body, query, headers)
builder.Services.AddProblemDetails();

public sealed record CreateOrder(
    [property: Required, StringLength(40)] string CustomerRef,
    [property: Range(1, 100)] int Quantity,
    [property: Required] string Sku);

app.MapPost("/orders", (CreateOrder cmd, IOrderService svc, CancellationToken ct) => svc.CreateAsync(cmd, ct))
   .WithName("CreateOrder");
// Invalid input -> 400 with a ValidationProblemDetails body, before the handler runs.
// Opt out per endpoint with .DisableValidation() when you validate elsewhere.
نوع القاعدةمكانهامثال
Shape/syntaxDataAnnotations أو FluentValidation على الـ DTOrequired، طول، range، format
Cross-fieldIValidatableObject أو FluentValidationEndDate > StartDate
Business/semanticالـ domain/application layer«الـ SKU موجود ومتاح للـ tenant ده»
Uniquenessالـ database constraint (ضمان) + فحص مسبق (رسالة لطيفة)email مش متكرر

التفاصيل (الأنواع لازم تكون public، دعم الـ nested objects) راجعها في docs الـ validation الرسمية لنسختك — reviewed 2026-11-18.

08

Endpoint filters: الـ pipeline بالترتيب

How filters wrap a handler
Deep dive
Routing + bindinggroup filters (outer) → endpoint filters (inner)Tenant filtergroupValidationendpointHandlerIResultserializeA filter can short-circuit (return a result) without calling next
Endpoint filters wrap the handler like middleware, but with access to bound arguments
C#a reusable idempotency filter for POST endpoints
public sealed class IdempotencyFilter(IIdempotencyStore store) : IEndpointFilter
{
    public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var key = ctx.HttpContext.Request.Headers["Idempotency-Key"].ToString();
        if (string.IsNullOrWhiteSpace(key)) return TypedResults.Problem("Idempotency-Key header required", statusCode: 400);
        if (await store.TryGetAsync(key) is { } saved) return saved;              // replay the first response
        var result = await next(ctx);
        await store.SaveAsync(key, result, TimeSpan.FromHours(24));
        return result;
    }
}

var orders = app.MapGroup("/orders").RequireAuthorization().AddEndpointFilter<TenantFilter>();
orders.MapPost("/", CreateOrderHandler.Handle).AddEndpointFilter<IdempotencyFilter>();

الفرق عن الـ middleware: الـ filter بيشتغل بعد الـ routing والـ binding، فشايف الـ arguments المتربطة والـ endpoint metadata، وبيتطبق على endpoints محددة. الـ middleware أنسب لحاجات لكل request (logging، exception handling، CORS). التفاصيل في Middleware.

09

Vertical slices: تنظيم Minimal APIs في مشروع حقيقي

Feature folders that scale
Practical
Textfeature-first layout
src/Shop.Api/
  Features/
    Orders/
      CreateOrder.cs        // request record + validator + handler + MapEndpoint extension
      GetOrder.cs
      OrdersModule.cs       // MapGroup("/orders") + shared filters + tags
    Billing/
      ...
  Program.cs                // app.MapOrders(); app.MapBilling();
C#CreateOrder.cs: everything for one use case in one place
public static class CreateOrder
{
    public sealed record Request(string Sku, int Quantity);
    public sealed record Response(Guid Id, decimal Total);

    public static RouteHandlerBuilder Map(RouteGroupBuilder g) =>
        g.MapPost("/", Handle).WithName(nameof(CreateOrder)).Produces<Response>(201).ProducesValidationProblem();

    public static async Task<Results<Created<Response>, ValidationProblem, Conflict>> Handle(
        Request req, AppDb db, ITenantContext t, CancellationToken ct)
    {
        var product = await db.Products.SingleOrDefaultAsync(p => p.Sku == req.Sku, ct);   // query filter scopes the tenant
        if (product is null) return TypedResults.ValidationProblem(new Dictionary<string, string[]> { ["sku"] = ["Unknown SKU"] });
        if (product.Stock < req.Quantity) return TypedResults.Conflict();
        var order = Order.Place(t.TenantId, product, req.Quantity);
        db.Orders.Add(order);
        await db.SaveChangesAsync(ct);
        return TypedResults.Created($"/orders/{order.Id}", new Response(order.Id, order.Total));
    }
}

الـ Results<...> union بيخلي الـ OpenAPI يعرف كل status codes الممكنة من غير attributes، وبيخلي الـ compiler يمنعك ترجع نوع مش متوقع. ده نفس هدف OpenAPI: الـ contract جاي من الكود نفسه.

10

Knowledge Check

Minimal API design
Basics
هل Minimal API معناها أن كل التطبيق لازم يكون في Program.cs؟
لا. endpoints يمكن تجميعها في route modules و features وخدمات مستقلة.
لماذا TypedResults مفيدة؟
توضح response alternatives للـ compiler والـ OpenAPI metadata وتقلل غموض العقد.
هل إخفاء endpoint من OpenAPI يحميه؟
لا. الحماية تأتي من authorization policy أو middleware أو network controls، وليس من إخفاء الوثيقة.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

خريطة التغطية: 10 عنصر من الـ Roadmap ومكان شرحه في الدرس
RoadmapEndpoint Mapping§01
RoadmapRoute Groups§01
RoadmapParameter Binding§02
RoadmapResults and Typed Results§02
RoadmapDependency Injection§03
RoadmapValidation§03
RoadmapAuthentication and Authorization§04
RoadmapEndpoint Filters§04
RoadmapOpenAPI§04
RoadmapOrganizing Larger Applications§05

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس