ASP.NET Web API interview questions and answers

Core Definition and Architecture

ASP.NET Core Web API is a subset of ASP.NET Core optimized for generating HTTP responses serialized typically as JSON. Unlike MVC controllers which often return HTML views, API controllers focus on data exchange using standard HTTP verbs like GET, POST, PUT, and DELETE. It integrates deeply with the middleware pipeline, handling routing, model binding, and content negotiation automatically. This architecture supports both controller-based patterns and Minimal APIs, providing flexibility for different service sizes.

Typical Use Cases

• RESTful Services: Exposing resources via standard URI patterns and HTTP methods for stateless communication.

• Mobile and SPA Backends: Serving data to Angular, React, iOS, or Android clients that require JSON payloads.

• Microservices: Building lightweight, independently deployable services that communicate over HTTP within a distributed system.

• Third-Party Integrations: Providing public endpoints for external developers to interact with your platform securely.

• Server-to-Server Communication: Allowing backend systems to exchange data programmatically without a user interface.

Key Characteristics in .NET 8

Modern development distinguishes between classic ASP.NET Web API 2 (legacy, .NET Framework) and ASP.NET Core Web API. In .NET 8, the framework emphasizes: - Controller-based APIs: Using [ApiController] and ControllerBase to enable automatic model validation and attribute routing. - Minimal APIs: Introduced in .NET 6 and matured in .NET 8, this pattern uses MapGet, MapPost, and other mapping methods without controllers, suitable for smaller services or microservices. - Problem Details: Errors are returned following RFC 9457 (application/problem+json) using Problem() or ValidationProblem(), replacing the older RFC 7807 format. - Automatic 400 Responses: With [ApiController], invalid model state automatically triggers a 400 Bad Request without manual checks. - Content Negotiation: Responses can be serialized as JSON, XML, or other formats based on the client’s Accept header.

Best Practices and Security

• Authentication: Secure endpoints using JWT bearer tokens or ASP.NET Core Identity, ensuring UseAuthentication() precedes UseAuthorization() in the middleware pipeline.

• CORS: Configure CORS explicitly using policies; never allow any origin together with credentials enabled.

• Versioning: Use the Asp.Versioning.Mvc package for API versioning; avoid the deprecated Microsoft.AspNetCore.Mvc.Versioning.

• Documentation: In .NET 8, templates typically configure Swashbuckle (AddSwaggerGen) for OpenAPI documentation, though .NET 9 shifts toward Microsoft.AspNetCore.OpenApi.

• Rate Limiting: Enable built-in rate limiting via AddRateLimiter to protect resources from abuse.

• HTTP Clients: When calling downstream services, use IHttpClientFactory instead of instantiating HttpClient directly to avoid socket exhaustion.

Classic Architecture Differences

In the .NET Framework era, these technologies served distinct roles. ASP.NET Web API used the ApiController base class to handle HTTP requests and return serialized data. ASP.NET MVC used the Controller base class to render Razor views for browsers. WCF used [ServiceContract] interfaces to expose operations over SOAP, TCP, or HTTP, relying on configuration-heavy web.config settings. Web API 2 specifically utilized WebApiConfig for routing, distinct from MVC’s RouteConfig.

Protocol and Message Semantics

Web API adheres strictly to HTTP semantics: GET and PUT are idempotent, POST creates resources, and status codes like 201 Created or 404 Not Found convey outcomes. WCF wraps messages in SOAP envelopes with WS-* standards for security and reliability, adding overhead. MVC focuses on HTML output, though it can return JSON via JsonResult. Error handling in modern APIs uses Problem Details (RFC 9457) via Problem(), whereas WCF uses SOAP Faults. In classic Web API, errors were often returned as HttpResponseMessage or custom objects.

Modern Unification in .NET 8

In ASP.NET Core (including .NET 8), Web API and MVC are unified into a single framework. Controllers inherit from ControllerBase (for APIs) or Controller (for views), sharing the same pipeline. Minimal APIs offer an alternative without controllers. WCF is not supported for service hosting on .NET Core/8; existing WCF services should be migrated to HTTP APIs or gRPC. OpenAPI documentation uses Swashbuckle in .NET 8 (AddSwaggerGen), replacing earlier WCF metadata endpoints.

Selection Guidelines and Best Practices

For new development, choose ASP.NET Core Web API on .NET 8. Use [ApiController] for automatic model validation (returning 400) and attribute routing. Secure endpoints with JWT bearer authentication, ensuring UseAuthentication precedes UseAuthorization. Configure CORS explicitly rather than allowing any origin with credentials. Return errors as Problem Details using Problem() for RFC 9457 compliance. Avoid starting new projects with WCF or classic Web API 2 unless maintaining legacy systems.

Comparison Summary

This table clarifies the historical distinctions while highlighting the current unified state. Understanding these differences is crucial for maintaining legacy enterprise systems while designing modern cloud-native solutions.

The REST Architectural Constraints

A service is only truly RESTful when it respects these constraints:

• Client–server: Clients and servers evolve independently; the UI (client) is separated from data storage and business logic (server).

• Statelessness: Each request contains everything the server needs to process it. No server-side session state is relied on between requests, which improves scalability and reliability.

• Cacheable: Responses explicitly declare whether they are cacheable (via Cache-Control, ETag, Last-Modified), letting clients and intermediaries reuse them.

• Uniform interface: Resources are identified by URIs (e.g. /orders/42), representations are JSON or XML, messages are self-descriptive (media types, headers), and hypermedia links guide transitions (HATEOAS).

• Layered system: Clients cannot tell whether they connect directly to the server or to an intermediary (load balancer, proxy, gateway).

• Code on demand (optional): Servers may temporarily extend client behaviour by sending executable code, such as JavaScript.

REST Compared with RPC and SOAP

How ASP.NET Core Web API Maps to REST

• Resources become controllers: a controller class such as OrdersController groups the operations for a resource, decorated with [ApiController] and an attribute route like [Route("api/[controller]")].

• HTTP verbs map to action methods: [HttpGet], [HttpPost], [HttpPut], [HttpPatch] and [HttpDelete] select the action based on the request method, so the same URI (/orders/42) behaves differently for GET and DELETE.

• Content negotiation: the framework reads the Accept header and serializes responses as JSON by default (System.Text.Json), falling back to other formatters when configured.

• Meaningful status codes: ActionResult<T> and IActionResult let actions return 200 OK, 201 Created with a Location header, 204 No Content, 400, 404, 409 Conflict or 500, matching REST’s self-descriptive message requirement.

• Standardized errors: AddProblemDetails() plus Problem() and ValidationProblem() emit application/problem+json (RFC 9457), and with [ApiController] an invalid model automatically produces a 400 validation error.

HTTP Semantics That Make It Work

• GET is safe and idempotent: repeated calls have no side effects and must not modify state.

• PUT is idempotent: sending the same representation repeatedly yields the same result.

• DELETE is idempotent: deleting a resource twice leaves it deleted.

• POST is neither safe nor idempotent: each call creates a new subordinate resource and should return 201 Created.

Best Practices and Common Pitfalls

• Use plural nouns for resource collections (/orders, /customers/7/orders) and keep verbs out of URIs; the HTTP method already carries the action.

• Version the API from the start with the Asp.Versioning.Mvc package; Microsoft.AspNetCore.Mvc.Versioning is the old, deprecated package.

• Always serve over HTTPS, authenticate with JWT bearer or ASP.NET Core Identity, and configure CORS explicitly — never combine “allow any origin” with credentials.

• Return errors consistently as Problem Details rather than ad-hoc JSON, and use the correct status code instead of blanket 200 OK responses.

• A common pitfall is calling an API “RESTful” while it tunnels actions through GET or POST (for example, POST /orders/cancel/42); that is RPC over HTTP, not REST.

Core Structure and Attributes

The controller class must derive from ControllerBase rather than Controller if you do not need view rendering support, which reduces overhead. Applying [ApiController] at the class level enforces API-specific behaviors, such as automatic 400 responses for invalid model states and binding source parameter inference. Routing is configured using [Route("api/[controller]")], which dynamically inserts the controller name into the URL path, ensuring consistent endpoint addressing.

Action Methods and HTTP Verbs

Each public method maps to an HTTP verb using attributes like [HttpGet], [HttpPost], [HttpPut], and [HttpDelete]. GET, PUT, and DELETE operations should be idempotent, while POST creates new resources. Return types should be ActionResult<T> to allow flexibility; for instance, returning Ok(product) yields a 200 status, while NotFound() yields a 404. When creating resources, return CreatedAtAction to provide a 201 status with a Location header pointing to the new resource.

Error Handling and Problem Details

Errors should be returned using the Problem Details format (RFC 9457), which standardizes error responses across the API and replaces RFC 7807. In Program.cs, register this support via builder.Services.AddProblemDetails(). Within the controller, use Problem(), ValidationProblem(), or specific helpers like BadRequest() and Conflict() to generate compliant payloads. With [ApiController], model validation failures automatically trigger a 400 response without explicit checks.

Minimal APIs Alternative

For simpler scenarios, Minimal APIs allow defining endpoints directly in Program.cs using MapGet, MapPost, etc., without controller classes. You can use TypedResults to maintain strong typing similar to ActionResult<T>. Choose controllers for larger applications requiring organization and filters, and Minimal APIs for microservices or rapid prototyping.

Code Example

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}")]
    public ActionResult<Product> GetProduct(int id)
    {
        var product = FetchProduct(id);
        if (product is null) return NotFound();
        return product;
    }

    [HttpPost]
    public async Task<ActionResult<Product>> CreateProduct(Product product)
    {
        // ModelState invalid returns 400 automatically due to [ApiController]
        var created = await SaveProductAsync(product);
        return CreatedAtAction(nameof(GetProduct), new { id = created.Id }, created);
    }
}

Note that AddProblemDetails() should be called in Program.cs to ensure error responses follow RFC 9457.

Best Practices and Common Pitfalls

• [Authorize]: Secure endpoints using JWT bearer authentication or ASP.NET Core Identity, ensuring UseAuthentication precedes UseAuthorization in the middleware pipeline.

• HttpClient: Never instantiate HttpClient directly; inject IHttpClientFactory for external HTTP calls to avoid socket exhaustion.

• CORS: Configure CORS policies explicitly; never combine AllowAnyOrigin with AllowCredentials.

• Versioning: Use the Asp.Versioning.Mvc package for API versioning, avoiding the deprecated Microsoft.AspNetCore.Mvc.Versioning.

• Validation: Rely on automatic model validation provided by [ApiController] rather than manual ModelState.IsValid checks.

How Routing Works

• The routing middleware evaluates the request path against registered route templates in order.

• For controller-based APIs, the framework scans assemblies for [Route] and HTTP verb attributes at startup and builds a route table.

• When a route matches, model binding maps URL segments, query strings, headers, and the request body to action parameters.

• If no route matches, the framework returns 404; if the path matches but the HTTP method does not, it returns 405.

• With [ApiController] applied, an invalid model state automatically returns a 400 response as Problem Details.

Attribute Routing on Controllers

• [Route("api/[controller]")] sets a base path, where [controller] is replaced by the controller class name without the “Controller” suffix.

• HTTP verb attributes ([HttpGet], [HttpPost], [HttpPut], [HttpDelete]) select the method and can carry their own template.

• Route parameters use {id} syntax and bind to action parameters of the same name.

• Optional parameters use {id?}, and constraints like {id:int} or {slug:alpha} restrict matches.

• Token replacement also supports [action] for the method name.

Minimal APIs as an Alternative

• Minimal APIs define routes directly on the WebApplication using MapGet, MapPost, MapPut, and MapDelete with a string pattern.

• Patterns support the same {parameter} syntax and route constraints.

• TypedResults provides strongly-typed results (e.g., TypedResults.Ok, TypedResults.Created) and is the recommended style for Minimal APIs.

• Controller-based and Minimal API routes coexist in the same route table and follow the same matching rules.

Route Precedence and HTTP Semantics

• Endpoint routing ranks matching candidates by route precedence first — literal segments outrank parameters, and constrained parameters ({id:int}) outrank unconstrained ones ({id}) — and uses registration order only as a tiebreaker, so a specific template wins even when registered after a general one.

• Ambiguous matches, where two actions match with equal precedence and order, throw an AmbiguousMatchException at runtime.

• Use POST for non-idempotent creation (return 201 with a Location header), PUT for idempotent replacement, and DELETE for idempotent removal (return 204 No Content).

Code Example

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IProductService _service;

    public ProductsController(IProductService service) => _service = service;

    // GET api/products
    [HttpGet]
    public ActionResult<IEnumerable<Product>> GetAll() => Ok(_service.GetAll());

    // GET api/products/5
    [HttpGet("{id:int}")]
    public ActionResult<Product> GetById(int id) => _service.GetById(id) is { } p ? Ok(p) : NotFound();

    // POST api/products -> 201 Created with Location header
    [HttpPost]
    public ActionResult<Product> Create([FromBody] ProductDto dto)
    {
        var product = _service.Create(dto);
        return CreatedAtAction(nameof(GetById), new { id = product.Id }, product);
    }

    // PUT api/products/5 (idempotent)
    [HttpPut("{id:int}")]
    public IActionResult Update(int id, [FromBody] ProductDto dto) => NoContent();

    // DELETE api/products/5 (idempotent) -> 204 No Content
    [HttpDelete("{id:int}")]
    public IActionResult Delete(int id) => NoContent();
}

Common Pitfalls

• Do not mix attribute routing and convention-based routing inconsistently; attribute routing is preferred for APIs.

• Add constraints such as :int to route parameters to make templates specific and avoid AmbiguousMatchException between overlapping templates.

• Never return 200 for resource creation; use 201 with CreatedAtAction or CreatedAtRoute so clients can follow the Location header.

• Remember that GET, PUT, and DELETE must be idempotent; only POST is non-idempotent.

How It Works

Routing runs inside the endpoint-routing middleware pipeline: UseRouting() resolves the matching endpoint, authorization and other middleware act on that endpoint, and the endpoint is executed by the MVC action invoker.

1. The request URL is compared against every registered route template (controller template + action template).

2. Candidates whose HTTP method does not match the verb attribute ([HttpGet], [HttpPost], …) are eliminated.

3. Route constraints such as {id:int} are validated.

4. Remaining candidates are scored by specificity — literal segments beat parameters, more constraints beat fewer, and required parameter lists must be bindable.

5. The best match wins; no match at all produces a 404 Not Found, and two truly equal matches throw AmbiguousMatchException, so templates must be unambiguous.

Route Templates

• [Route("api/[controller]")] on the controller class applies to every action in it; the [controller], [action] and [area] tokens are replaced at startup from the controller and action names.

• Verb attributes carry their own segment, e.g. [HttpGet("{id:int}")], which is appended to the class template.

• Parameters are optional when suffixed with ? ({id:int?}), and defaults can be set inline ({culture=en}).

• app.MapControllers() in Program.cs registers the endpoints for attribute-routed actions. Conventional routing via MapControllerRoute("{controller}/{action}/{id?}") exists but is aimed at MVC views; APIs rely on attribute routing, and [ApiController] enforces it.

HTTP Method Attributes

[HttpGet], [HttpPost], [HttpPut], [HttpPatch], [HttpDelete], [HttpHead] and [HttpOptions] both constrain the verb and contribute the route. Semantically, GET, PUT and DELETE are idempotent, while POST is not, so POST is used for creation and other non-repeatable operations. Successful creation returns 201 Created with a Location header, typically produced with CreatedAtAction(...); full updates and deletions return 204 No Content.

Parameter Binding

With [ApiController], binding sources are inferred: simple types bind from route values and query string, complex types from the body via [FromBody], and the framework also infers [FromQuery], [FromRoute], [FromHeader] and [FromForm] when it can. Explicit attributes override inference. Invalid or missing model state automatically produces a 400 response with application/problem+json (RFC 9457) — no manual ModelState check is needed.

Minimal APIs as the Alternative

Minimal APIs expose the same routing engine through MapGet, MapPost, MapPut and MapDelete on IEndpointRouteBuilder, returning TypedResults for statically typed results. There is no action-selection step: one delegate is bound to one route and verb, which removes ambiguity but also removes class-level template composition.

Best Practices and Common Pitfalls

• Use plural resource nouns and verbs, not RPC-style action names: api/products/{id} rather than api/products/GetProductById.

• Add constraints such as :int, :guid, :minlength(3) or :regex(...) so malformed URLs fail routing with a 404 instead of reaching your action.

• Avoid two actions with the same template and verb; differentiate them with distinct templates or constraints, otherwise routing becomes ambiguous.

• Return proper status codes: 200, 201 with Location, 204, 404 and 400 validation errors, and let AddProblemDetails() plus Problem() / ValidationProblem() shape all error payloads.

• Keep async all the way through the action and any data-access or IHttpClientFactory calls; blocking inside an action wastes thread-pool threads.

How It Works

When a client sends a request, the framework performs the following steps:

1. The client includes an Accept header listing the media types it can handle, optionally with quality values (q), e.g. Accept: application/json, application/xml;q=0.8.

2. The action returns an object (e.g. Ok(product) or an ActionResult<T>).

3. The framework’s output-formatter selector examines the registered IOutputFormatter instances in the order they were added.

4. The first formatter whose supported media types intersect with the client’s Accept list is chosen.

5. That formatter serializes the object and writes the response, setting the matching Content-Type header.

If the client sends no Accept header or sends /, the first registered formatter (JSON by default) is used. If the client requests a specific media type that no formatter supports, the framework returns 406 Not Acceptable.

Key Components

• Accept header: declares the client’s preferred media types; quality values let the client express relative preference.

• Output formatters: SystemTextJsonOutputFormatter (JSON, default) and XmlDataContractSerializerOutputFormatter / XmlSerializerOutputFormatter (XML, added explicitly). They implement IOutputFormatter.

• Input formatters: the reverse path; they deserialize the request body into action parameters during model binding.

• Content-Type response header: indicates the actual media type of the response body.

• Produces attribute: restricts an action to a specific set of media types; if the client asks for something outside that set, the framework returns 406 Not Acceptable.

Default Behaviour and Configuration

JSON is the default format in .NET 8, provided by System.Text.Json. XML support is not enabled by default; you add it in Program.cs with AddXmlSerializerFormatters() or AddXmlDataContractSerializerFormatters(). These formatters are part of the shared framework, so no extra NuGet package is required. Once registered, XML participates in negotiation like any other formatter.

You can also restrict an action to a single format with [Produces("application/json")]. This both documents the contract in OpenAPI and forces a 406 response when a client requests an unsupported type.

JSON vs XML Support

Best Practices and Common Pitfalls

• Return objects, not serialized strings: return Ok(product) and let the formatter serialize it. Returning a pre-serialized string pins the response to one format and defeats negotiation.

• Use [Produces] to document and constrain formats, which also improves OpenAPI output.

• Do not rely on the browser Accept header: browsers often send Accept: text/html, which an API cannot produce; test with tools such as curl or Postman.

• Validate the Accept header carefully: accepting arbitrary client-supplied media types can leak format choices you did not intend to expose.

• Prefer JSON unless XML is required by an integration partner; JSON is faster, smaller, and the default for modern clients.

• Minimal APIs handle this differently: they return IResult objects (e.g. Results.Json(product)) that explicitly set Content-Type, so there is no automatic negotiation based on Accept.

Authentication and Authorization

• Authentication: prove who the caller is. Use JWT bearer tokens (AddJwtBearer) for service-to-service or SPA scenarios, or ASP.NET Core Identity for user accounts. The token travels in the Authorization: Bearer header.

• Authorization: decide what an authenticated caller may do. Apply [Authorize] on controllers or actions, and prefer policies for claims-based checks over hard-coded roles.

• Token handling: validate signatures, expiry, and issuer; rotate signing keys and keep token lifetimes short to limit the impact of a leaked token.

• Status codes: an unauthenticated request returns 401; an authenticated caller lacking permission returns 403.

HTTPS and CORS

• Enforce HTTPS with UseHttpsRedirection() plus a reverse-proxy or production redirection rule. This applies on both Windows and Linux hosts.

• Consider HTTP Strict Transport Security (HSTS) so clients only ever connect over HTTPS after the first visit.

• Configure CORS explicitly with a named policy. Never combine AllowAnyOrigin() with AllowCredentials(); browsers reject that combination. List exact origins, methods, and headers.

• CORS is enforced by the browser, so it protects web clients; server-to-server callers still need authentication.

Rate Limiting and Input Validation

• Use the built-in rate limiting middleware (AddRateLimiter, .NET 7+) to throttle clients and blunt denial-of-service or credential-stuffing attacks. A throttled request returns 429.

• Choose limits per endpoint based on cost: login and token endpoints need tighter limits than read-only queries.

• [ApiController] automatically returns 400 when model binding or data annotations fail, so business logic never runs on invalid input.

• Validate and encode any data you reflect back, and never trust route or query values.

Secrets and Error Handling

• Keep keys, connection strings, and signing secrets out of code. Use user secrets in development and environment variables or a vault in production.

• Never log secrets or tokens, and ensure your logging provider redacts sensitive headers.

• Return errors as Problem Details (application/problem+json, RFC 9457) via AddProblemDetails() and Problem(). This standardizes error payloads and prevents stack traces from leaking.

• When calling other services, create HttpClient through IHttpClientFactory (named or typed clients) and use async all the way; never instantiate a new HttpClient per request.

Common Pitfalls

• Calling UseAuthorization() before UseAuthentication() means policies never see the user.

• Using AllowAnyOrigin() with credentials silently breaks in browsers.

• Returning raw exceptions or validation details in production exposes internals; Problem Details keeps payloads consistent.

• Treating CORS as a security boundary; it is a browser feature, not authentication.

• Using weak or hardcoded JWT signing secrets; store them in a vault and rotate them.

Kestrel: The Default Server

• Cross-platform: Kestrel runs on Windows, Linux and macOS, and is the server the .NET 8 templates configure automatically.

• Built in: No extra package is needed; it ships as part of Microsoft.AspNetCore.App.

• Features: Supports HTTP/1.1, HTTP/2 and HTTP/3 (HTTP/3 requires explicit enablement and platform support for QUIC), TLS, and Unix domain sockets on Linux.

• Usage: For most APIs you call builder.Build() and app.Run() with no extra setup; Kestrel binds to the URLs from ASPNETCORE_URLS, launchSettings.json or the --urls command-line argument.

Running Behind a Reverse Proxy

In production, Kestrel should sit behind a reverse proxy:

• IIS (Windows only): Uses the ASP.NET Core Module (ANCM) to forward requests. Since .NET Core 3.0 the default is in-process hosting, where requests execute inside the IIS worker process.

• nginx or Apache (Linux): Terminate TLS, serve static files and forward to Kestrel on a local port or Unix socket.

• Why: The proxy provides port sharing, request filtering, TLS certificate management and protection against edge-case protocol attacks that Kestrel does not fully guard against on its own.

Windows-Only Alternatives

• HTTP.sys: A kernel-mode HTTP driver available only on Windows. Choose it over Kestrel when you need Windows authentication at the server level or when several apps must share a single port without a reverse proxy. Configure it with builder.WebHost.UseHttpSys().

• IIS out-of-process: The older model where ANCM launches Kestrel as a separate process; still supported but in-process hosting is preferred on .NET 8.

Containers and Cloud

• Docker: Package the app in a Linux or Windows container; Kestrel listens on the exposed port. This is the most common deployment shape on Kubernetes (AKS, EKS, GKE).

• Azure App Service: Manages the web server and reverse proxy for you; you deploy the compiled app or a container image.

• Azure Container Apps / AWS ECS: Managed container hosting with built-in scaling and no server administration.

Code Example

Endpoints and limits are configured in appsettings.json or directly in code. The following shows programmatic Kestrel configuration:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseKestrel(options =>
{
    options.ListenAnyIP(5000);                       // HTTP endpoint
    options.ListenAnyIP(5001, listenOptions =>       // HTTPS endpoint
    {
        listenOptions.UseHttps();
    });
    options.Limits.MaxRequestBodySize = 10 * 1024 * 1024; // 10 MB
});

builder.Services.AddControllers();
var app = builder.Build();
app.MapControllers();
app.Run();

Best Practices and Common Pitfalls

• Never expose Kestrel directly to the public internet; always put a hardened reverse proxy in front.

• Use HTTPS everywhere; terminate TLS at the proxy and call app.UseForwardedHeaders() (with ForwardedHeadersOptions configured) so X-Forwarded-For and X-Forwarded-Proto are applied and the app computes correct URLs.

• Set explicit limits for request body size, keep-alive timeouts and concurrent connections to resist DoS attacks.

• Do not block threads; hosting threads are shared, so use async/await all the way through controllers.

• Add health checks with MapHealthChecks so load balancers and orchestrators can probe the app.

• Keep secrets out of configuration files; use user secrets in development and managed identities or a secret store in production.

What OWIN Is

• Specification: OWIN is a specification, not a library or product. It is documented at owin.org and exists to break the tight coupling between .NET web apps and the web server.

• Motivation: The motivation mirrors Rack in Ruby or WSGI in Python: without OWIN, ASP.NET Web API was bound to System.Web.dll and the IIS request pipeline, making it hard to host elsewhere or to compose lightweight middleware.

• Purpose: OWIN defines how a server passes a request to an application and how application components (middleware) chain together, leaving each side free to evolve independently.

The OWIN Application Delegate

• Application delegate: The entire spec centres on one delegate signature: Func<IDictionary<string, object>, Task>.

• Environment dictionary: The IDictionary<string, object> is the OWIN environment dictionary, carrying the request, response, headers, server variables and metadata as key-value pairs.

• Middleware chaining: Each middleware component receives the environment, can inspect or modify it, and calls the next delegate in the chain. The final delegate is the application itself, which produces the response.

How Web API Fits Into the OWIN Pipeline

• Traditional hosting: In traditional hosting, Web API 2 runs through IIS using Global.asax, WebApiConfig, and the ApiController base class tied to System.Web.

• OWIN integration: With OWIN, you build an HttpConfiguration, register routes on it, and plug it into the OWIN pipeline with app.UseWebApi(config) from the Microsoft.AspNet.WebApi.Owin package.

• Request flow: From that point the OWIN host receives raw HTTP, hands it to Web API’s HttpServer, and Web API selects the controller and action exactly as it would under IIS. The controllers themselves do not change.

Katana: Microsoft’s OWIN Implementation

• Katana: Katana is Microsoft’s official set of OWIN components and hosts.

• Key packages: Key NuGet packages include Microsoft.Owin (core types like IAppBuilder), Microsoft.Owin.Host.SystemWeb (runs OWIN middleware inside the IIS/System.Web pipeline), and Microsoft.Owin.SelfHost (runs OWIN in your own process).

• Startup: An OWIN application starts from a startup class marked with [assembly: OwinStartup(typeof(Startup))] containing a Configuration(IAppBuilder app) method where middleware and Web API are wired up.

OWIN Hosting vs Traditional IIS Hosting

OWIN and ASP.NET Core: When It Still Matters

• Core does not use OWIN: ASP.NET Core does not use OWIN. It ships its own built-in middleware pipeline and Kestrel server, which were inspired by OWIN but are a separate, first-party design.

• Modern recommendation: On .NET 8, new APIs should be built with ASP.NET Core middleware, not OWIN. OWIN remains relevant only for maintaining or migrating existing ASP.NET Web API 2 applications on .NET Framework 4.8.

• Incompatibility: Do not attempt to mix OWIN components into an ASP.NET Core pipeline; they are incompatible.

• Legacy hosting: You are maintaining a legacy Web API 2 codebase and need to host it outside IIS.

• Middleware extension: You want to add lightweight OWIN middleware (logging, authentication) in front of Web API without moving to Core yet.

• Greenfield guidance: For greenfield work, choose ASP.NET Core on .NET 8 instead, since OWIN receives no new features and the ecosystem has moved to Core’s native middleware model.

How IIS Hosting Works

• Your API is deployed as an ASP.NET application with a web.config file and runs inside w3wp.exe, the IIS worker process.

• Requests flow through the IIS integrated pipeline; HttpControllerHandler routes them to the Web API dispatch pipeline and your ApiController classes.

• Configuration lives in web.config (routes can also be registered in WebApiConfig.Register called from Global.asax).

• IIS manages the process lifecycle: it starts the app on the first request (or immediately with “Always Running”), recycles on schedule or memory thresholds, and restarts on crashes.

How Self-Hosting Works

• You create an HttpSelfHostConfiguration with your routes, then instantiate HttpSelfHostServer and call OpenAsync().

• The server runs in whatever process you own: a console application, a Windows service, or a background task.

• Under the hood it uses HttpListener, which listens on a base address such as http://localhost:8080/.

• You are responsible for starting and stopping the server, handling exceptions, and keeping the process alive.

Key Differences

When to Use Each

• Choose IIS hosting for production, internet-facing APIs: you get process recycling, rapid-fail protection, SSL termination, Windows authentication, logging, and integration with existing IIS infrastructure at no extra code.

• Choose self-hosting for internal tools, prototypes, test harnesses, or scenarios where IIS is unavailable or undesirable (for example, a utility that must run without an IIS dependency, or side-by-side versions of Web API on one machine).

• Self-hosting is also useful when you need the API to start before any HTTP request arrives, or when you want to host multiple independent Web API instances in one process.

Best Practices and Common Pitfalls

• Do not use self-hosting for public-facing production APIs unless you replicate IIS features yourself (request filtering, DDoS protection, TLS termination, process health monitoring).

• Run self-hosted endpoints over HTTPS; HttpListener supports HTTPS only with a certificate bound to the port via netsh.

• Dispose the server properly: wrap HttpSelfHostServer in a using or call CloseAsync() on shutdown, otherwise ports stay bound.

• Remember HttpListener requires administrator privileges to register non-localhost prefixes on Windows.

• Do not mix the two models in one project: IIS hosting references Microsoft.AspNet.WebApi.WebHost; self-hosting references Microsoft.AspNet.WebApi.SelfHost, and their configuration types are not interchangeable.

• Note: in ASP.NET Core this distinction disappears — Kestrel is the built-in cross-platform server and IIS acts as a reverse proxy or in-process host. This answer covers classic Web API 2 only.

What CORS Solves

Browsers block a script at https://app.example.com from calling an API at https://api.example.com unless the API explicitly allows it. CORS is the browser-enforced mechanism in which the server sends response headers such as Access-Control-Allow-Origin that grant that permission. It is browser-side protection: non-browser clients (curl, Postman, mobile apps) do not enforce it, so CORS is never a substitute for authentication or authorization.

Configuring a Policy

A policy is a named bundle of three permissions:

• Allowed origins: the exact schemes, hosts and ports that may call the API, e.g. https://app.example.com. Use WithOrigins for an explicit allow-list.

• Allowed headers: request headers the browser may send, set with AllowAnyHeader or WithHeaders.

• Allowed methods: HTTP verbs permitted, set with AllowAnyMethod or WithMethods.

Call AllowCredentials() only when the API relies on cookies or bearer tokens sent by the browser. Note that the framework rejects combining AllowAnyOrigin() with AllowCredentials(), because that would let any site send authenticated requests; you must list explicit origins instead.

Applying the Policy

Order in Program.cs matters: place UseCors after UseRouting and before UseAuthentication/UseAuthorization, so the CORS check happens before authentication and endpoint execution. A default policy applied via UseCors() covers every endpoint; a named policy applied via UseCors("PolicyName") can be overridden per endpoint.

For controller-based APIs, add [EnableCors("PolicyName")] to a controller or action method to apply a specific policy, and [DisableCors] where a cross-origin call must be refused. In Minimal APIs the equivalent is RequireCors("PolicyName") on a route group or endpoint. Keep the two styles distinct: attribute-based selection belongs to controllers, RequireCors to Minimal API endpoint metadata.

Preflight Requests

For requests that are not “simple” (methods other than GET/POST/HEAD, custom headers, non-simple content types), the browser first sends an OPTIONS preflight request. ASP.NET Core’s CORS middleware intercepts it and returns the permission headers without executing the endpoint, provided the requested method, header and origin match the policy. A policy that omits a needed header or verb causes the real request to fail in the browser, even when the endpoint itself would accept it.

Code Example

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// Register a named CORS policy with an explicit origin allow-list
builder.Services.AddCors(options =>
{
    options.AddPolicy("Frontend", policy =>
    {
        policy.WithOrigins("https://app.example.com", "https://admin.example.com")
              .AllowAnyHeader()
              .AllowAnyMethod()
              .AllowCredentials(); // allowed only with explicit origins
    });
});

var app = builder.Build();

app.UseRouting();
app.UseCors("Frontend");          // must run before auth and endpoint execution
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

app.Run();

using Microsoft.AspNetCore.Cors;
using Microsoft.AspNetCore.Mvc;

public record Product(int Id, string Name);

[ApiController]
[Route("api/[controller]")]
[EnableCors("Frontend")]         // applies the named policy to all actions here
public class ProductsController : ControllerBase
{
    [HttpGet("{id:int}")]
    public ActionResult<Product> Get(int id) => Ok(new Product(id, "Sample"));
}

Best Practices and Common Pitfalls

• Prefer explicit origins: AllowAnyOrigin in production weakens the API; keep a short, configurable allow-list read from appsettings.json or configuration.

• Never combine AllowAnyOrigin with AllowCredentials: it is rejected by design; use WithOrigins whenever cookies or browser-sent tokens are involved.

• Check the middleware order: UseCors placed after UseAuthorization or before UseRouting produces broken or missing headers.

• Do not treat CORS as a security control: it constrains browsers, not clients; protect endpoints with JWT bearer authentication or ASP.NET Core Identity.

• Debug from the browser, not Postman: a 200 in Postman does not prove the CORS headers are present; inspect the preflight OPTIONS response and the Access-Control-Allow-Origin header in browser devtools.

How It Works

With attribute routing, the route template is attached to the controller class and/or its actions, and the framework matches an incoming request by combining the templates:

• Controller-level template: [Route("api/[controller]")] applies to every action in the controller. The [controller] token is replaced at runtime with the controller name minus the Controller suffix, so ProductsController becomes api/products.

• Action-level template: [HttpGet("{id:int}")] adds a parameter segment to the verb-specific template. Templates on actions are relative to the controller template.

• HTTP verb attributes: [HttpGet], [HttpPost], [HttpPut], [HttpPatch] and [HttpDelete] both constrain the HTTP method and can carry a template, so a single action can be reached only through the intended verb.

• Route values and constraints: {id} becomes a route value bound to an action parameter; :int, :min(1), :guid, :regex() and others restrict matches, so GET /api/products/abc simply returns 404 instead of reaching the action and failing.

Key Features

• Multiple routes per action: one action can be decorated with several [HttpGet]/[Route] attributes, exposing the same logic under different URIs.

• Token replacement: [controller] and [action] keep templates in sync with naming, and [area] supports area-based APIs.

• Hierarchical, resource-oriented URIs: nested templates such as api/customers/{customerId}/orders/{orderId} map naturally to actions, which is awkward with a single conventional route.

• Co-location: the route lives next to the code it dispatches to, so reading or changing a controller shows its contract immediately.

• Works with API versioning: the Asp.Versioning.Mvc package composes version segments (for example [Route("api/v{version:apiVersion}/[controller]")]) with attribute templates. The older Microsoft.AspNetCore.Mvc.Versioning package is deprecated and replaced by Asp.Versioning.Mvc.

Attribute Routing vs. Conventional Routing

A controller-based API can mix both, but a single action uses one model: when [Route] or a verb attribute is present, that action is not reachable through conventional routes.

Benefits in Short

• Precise, predictable URLs: the exact URI an action serves is visible on the action, which keeps the API contract honest and easy to review.

• Clean REST semantics: verbs and templates live together, so GET /api/products/5, POST /api/products, PUT /api/products/5 and DELETE /api/products/5 all read as one resource model.

• Better maintainability: adding or renaming an action does not require touching a central route table, and code reviews show routing changes in context.

• First-class support for versioning and nested resources: hierarchical and versioned URIs are declared where they belong instead of being encoded in a global pattern.

Best Practices and Common Pitfalls

• Prefer one base template on the controller plus verb-specific templates on actions; avoid repeating the full path on every action.

• Use constraints (:int, :min(1)) so malformed segments never reach your code, and keep route parameter names identical to action parameter names for model binding.

• Keep templates stable once clients depend on them; changing a published route is a breaking change, so version new shapes with Asp.Versioning.Mvc instead of editing existing templates.

• Remember that [ApiController] makes attribute routing effectively the norm for APIs and turns invalid model state into an automatic 400 with Problem Details (application/problem+json, RFC 9457) — register it with AddProblemDetails() and return Problem()/ValidationProblem() for manual errors.

• Do not rely on route order to disambiguate overlapping templates; two actions matching the same verb and URI cause an AmbiguousMatchException at request time.

Standard Status Code Helpers

Controller actions should return ActionResult<T> to allow flexibility between returning a data payload and a status code result. Common helpers include Ok() for 200, NoContent() for 204, and NotFound() for 404. For resource creation, use CreatedAtAction() or CreatedAtRoute() to return 201 along with a Location header pointing to the new resource. Use Conflict() for 409 when a state conflict occurs, such as a duplicate unique key violation. These methods are defined on ControllerBase and produce correct HTTP semantics without manually constructing HttpResponseMessage objects.

Problem Details for Errors

Errors should be returned as Problem Details following RFC 9457 (application/problem+json). The Problem() method generates a standard problem response with type, title, status, and detail fields. When [ApiController] is enabled, invalid model state automatically triggers a 400 response using ValidationProblem(), so manual checks for ModelState.IsValid are usually unnecessary. You can configure default problem details behavior globally in Program.cs using builder.Services.AddProblemDetails(), which allows setting custom exception handlers or modifying the default ProblemDetailsOptions.

Minimal APIs and TypedResults

Minimal APIs offer an alternative pattern using endpoint delegates instead of controllers. To keep responses strongly typed and expose their status codes to OpenAPI, use the static helpers on the TypedResults class, such as TypedResults.Ok(), TypedResults.NotFound(), or TypedResults.ValidationProblem(). Returning a bare IResult does not declare those outcomes, so generated OpenAPI descriptions cannot infer the endpoint’s status codes; the untyped Results factory produces the same runtime responses without the metadata. Minimal APIs suit smaller services, while controllers remain common for larger structured applications requiring filters and conventions.

Code Example

public record Product(int Id, string Name);

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    // In-memory store stands in for a real repository
    private readonly Dictionary<int, Product> _products = new();

    [HttpGet("{id}")]
    public ActionResult<Product> Get(int id)
    {
        if (!_products.TryGetValue(id, out var product))
            return NotFound(); // 404 when the resource does not exist

        return Ok(product); // 200 with the payload
    }

    [HttpPost]
    public ActionResult<Product> Create(Product product)
    {
        // [ApiController] auto-returns 400 ValidationProblem if ModelState is invalid
        var created = new Product(Random.Shared.Next(1, 100_000), product.Name);
        _products[created.Id] = created;

        return CreatedAtAction(
            nameof(Get),
            new { id = created.Id },
            created); // 201 with a Location header to the new resource
    }

    [HttpPut("{id}")]
    public IActionResult Update(int id, Product product)
    {
        if (!_products.ContainsKey(id))
            return NotFound(); // 404 when the target does not exist

        if (_products.Values.Any(p => p.Name == product.Name && p.Id != id))
            return Conflict(); // 409 on a duplicate unique value

        _products[id] = product with { Id = id };
        return NoContent(); // 204 for a successful, body-less update
    }
}

Best Practices and Pitfalls

Always match the status code to the action semantics: GET should be safe, PUT and DELETE idempotent, and POST non-idempotent. Never return 200 for error conditions; use 4xx for client errors and 5xx for server failures. Avoid exposing sensitive stack traces in the detail field of problem details in production. Configure CORS explicitly and never combine AllowAnyOrigin with AllowCredentials. Finally, ensure authentication middleware (UseAuthentication) runs before authorization (UseAuthorization) in the request pipeline to secure endpoints correctly.

What It Is

• IHttpActionResult lives in the System.Web.Http namespace and defines a single method: Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken).

• Controller classes inherit from ApiController, whose helper methods (Ok, NotFound, BadRequest, Created, Content, and so on) return ready-made IHttpActionResult implementations.

• The framework invokes ExecuteAsync after the action completes, turning the result into the HttpResponseMessage that is serialized and sent to the client.

How the Pipeline Uses It

1. The action method executes and returns an IHttpActionResult instance.

2. Web API’s ApiControllerActionInvoker receives that result.

3. It calls ExecuteAsync, which constructs status code, headers, and content.

4. The resulting HttpResponseMessage passes through message handlers and formatters before reaching the client.

Because the response-building logic is separated from the action decision, you can assert on the result type in tests without needing an HTTP server or mocking HttpResponseMessage.

Common Result Types

Custom Results

• You can implement IHttpActionResult directly to encapsulate repeated response logic, such as a standardized error format or a special header.

• A custom implementation receives the controller context in ExecuteAsync, so it can use Request, Configuration, or Url to build links and content.

• Prefer returning existing helper methods when they cover the scenario; reserve custom implementations for behavior the built-in helpers cannot express.

Best Practices and Pitfalls

• Prefer helper methods like Ok and NotFound over manually constructing HttpResponseMessage; they are shorter and express intent.

• Return Task<IHttpActionResult> for async actions and await all I/O; never block on async code.

• Use Created for POST so clients receive the Location header pointing to the new resource; use 204 for DELETE.

• Validate ModelState explicitly in Web API 2; unlike ASP.NET Core’s [ApiController], Web API 2 does not return 400 automatically.

• Do not carry this pattern into ASP.NET Core: on .NET 8 use ActionResult<T> or IActionResult with [ApiController], and return Problem Details via Problem() for errors. IHttpActionResult is specific to the legacy .NET Framework pipeline.

Model Binding Mechanism

When a GET request arrives, the framework inspects the route and query string to match parameter names. - Primitive Types: Simple types like int, string, or Guid are bound automatically if names match. - Complex Types: Classes default to binding from the request body; add [FromQuery] to bind their properties from the query string. - Nullable Types: Use int? or string to handle missing values gracefully without throwing exceptions. - Explicit Binding: The [FromQuery] attribute forces the binder to look only at the query string, avoiding ambiguity with route data.

Accessing Request.Query Directly

Sometimes parameter names are dynamic or unknown at compile time. In such cases, inspect the IQueryCollection. - Controller Context: Inside a controller, use Request.Query["key"] which returns a StringValues object. - Minimal API Context: Within a map delegate, access HttpContext.Request.Query directly from the context parameter. - StringValues: This structure handles multiple values for a single key (e.g., ?ids=1&ids=2) without requiring arrays explicitly.

Controller vs Minimal API Syntax

The approach differs slightly depending on whether you use traditional controllers or Minimal APIs. - Controllers: Parameters are defined in the method signature of a ControllerBase derived class. - Minimal APIs: Parameters are captured in the lambda arguments of MapGet, MapPost, etc. - TypedResults: Minimal APIs can return Results.Ok() with metadata for OpenAPI documentation.

Validation and Security Considerations

Query strings are user input and must be treated as untrusted data. - Problem Details: Configure AddProblemDetails() in Program.cs to ensure all errors follow RFC 9457 format. - Model Validation: With [ApiController], invalid model state automatically returns a 400 Problem Details response. - Sensitive Data: Never pass secrets, tokens, or PII in query strings as they are logged in server logs and browser history.

Code Example

// Controller-based approach
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("search")]
    public IActionResult Search(
        [FromQuery] string? category,
        [FromQuery] int? page = 1,
        [FromQuery] int? pageSize = 10)
    {
        if (pageSize > 100)
            return Problem("PageSize exceeds maximum", statusCode: 400);

        return Ok(new { Category = category, Page = page });
    }
}

// Minimal API approach
app.MapGet("/products/search", (string? category, int? page = 1) =>
{
    return Results.Ok(new { Category = category, Page = page });
});

Common Pitfalls

• Missing Values: Non-nullable value types (e.g., int) cause a 400 if the query parameter is missing; use nullable types instead.

• Binding Sources: Without [FromQuery], simple types on a GET are bound from route data and query string; a name matching both causes an ambiguity error.

• Collection Binding: To bind lists, use repeated keys (?id=1&id=2) or comma-separated values depending on binder configuration.

What the Classes Represent

• HttpRequestMessage: represents the incoming request. Its key members are Method (HttpMethod), RequestUri, Headers (HttpRequestHeaders), Content (HttpContent), and Properties, a per-request dictionary used to share state between handlers, filters and controllers.

• HttpResponseMessage: represents the outgoing response. Its key members are StatusCode (HttpStatusCode), ReasonPhrase, Headers (HttpResponseHeaders), Content (HttpContent), IsSuccessStatusCode, and RequestMessage, which links the response back to the request that produced it.

• Both are immutable in intent but mutable in practice: you construct a response, set its parts, and hand it back; the framework never reuses a request or response object across calls.

Reading Request Data

Extension methods in System.Net.Http.Formatting make the request easy to interrogate without parsing raw bytes:

• Request.GetQueryNameValuePairs(): parsed query string as key/value pairs.

• Request.GetRouteData(): the matched route values, useful in handlers where no controller context exists.

• Request.Headers.GetValues(...) / Request.Headers.TryGetValues(...): safe header lookup, since duplicate or missing headers otherwise throw.

• Request.Content.ReadAsAsync<T>(): deserialises the body via the configured formatters; in a controller you normally let model binding do this through an action parameter instead.

• Request.Properties: the right place to stash request-scoped data (correlation id, resolved tenant) so handlers and filters can read it later.

Building Responses

Responses are usually created with the Request.CreateResponse(...) extension methods, which run content negotiation against the request’s Accept header and pick a MediaTypeFormatter:

Because CreateResponse uses the request’s Accept header, the same action can return JSON or XML without action-level branching.

Code Example

using System;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using System.Web.Http;

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public interface IProductRepository
{
    Product GetById(int id);
    Task AddAsync(Product product);
}

public class ProductsController : ApiController
{
    private readonly IProductRepository _repository;

    public ProductsController(IProductRepository repository)
    {
        _repository = repository;
    }

    // GET api/products/5
    public HttpResponseMessage Get(int id)
    {
        var product = _repository.GetById(id);

        if (product == null)
        {
            // 404 with a negotiated body
            return Request.CreateResponse(
                HttpStatusCode.NotFound, "Product not found");
        }

        // 200 OK, body serialised by content negotiation
        var response = Request.CreateResponse(HttpStatusCode.OK, product);

        // Full control over response headers when you need it
        response.Headers.CacheControl =
            new System.Net.Http.Headers.CacheControlHeaderValue
            {
                Public = true,
                MaxAge = TimeSpan.FromMinutes(5)
            };

        return response;
    }

    // POST api/products
    public async Task<HttpResponseMessage> Post([FromBody] Product product)
    {
        if (!ModelState.IsValid)
        {
            // 400 with validation details
            return Request.CreateErrorResponse(
                HttpStatusCode.BadRequest, ModelState);
        }

        await _repository.AddAsync(product);

        // 201 Created with a Location header pointing at the new resource
        var created = Request.CreateResponse(HttpStatusCode.Created, product);
        created.Headers.Location = new Uri(Url.Link("DefaultApi",
            new { id = product.Id }));

        return created;
    }
}

Best Practices and Pitfalls

• Prefer IHttpActionResult for ordinary actions and reach for HttpResponseMessage only when you must set headers, stream content, or return a status the helpers do not cover.

• Always set Location on 201 Created so clients can navigate to the created resource; Url.Link keeps the route template in one place.

• Do not read the request body twice: ReadAsAsync consumes the stream; in controllers, use model binding instead of manual reads.

• Do not share HttpRequestMessage across requests: its Properties bag and disposal semantics are per-request; reuse causes stale state and ObjectDisposedExceptions.

• Return Task<HttpResponseMessage> for async work and avoid .Result/.Wait(), which can deadlock in the request synchronisation context.

• Keep handlers stateless: put per-request state in Request.Properties rather than static fields.

Attribute-Level Enforcement

• [RequireHttps] (Microsoft.AspNetCore.Mvc) is an authorization filter. For safe verbs (GET/HEAD) it short-circuits the request with a RedirectResult, returning 307 Temporary Redirect to the HTTPS scheme; for other verbs (POST, PUT, PATCH, DELETE) it throws RequireHttpsException, which the framework surfaces as 400 Bad Request — non-safe verbs are never redirected.

• Scope: apply it to a single action, to a whole controller class, or register it once as a global filter with services.AddControllers(o => o.Filters.Add(new RequireHttpsAttribute())) when you want attribute semantics everywhere.

• Minimal APIs: [RequireHttps] is an MVC filter, so it suits controller-based APIs; for Minimal APIs rely on redirection middleware plus authorization rather than this attribute.

Global Middleware Enforcement

• UseHttpsRedirection() redirects every HTTP request to HTTPS regardless of verb. It is configured through HttpsRedirectionOptions: RedirectStatusCode (default 307) and HttpsPort (default unset, in which case the port is discovered from the server’s bound HTTPS addresses).

• Ordering: call app.UseHsts() before app.UseHttpsRedirection(), and place both early in the pipeline — before static files and routing — so requests are upgraded before endpoint execution.

• Combining the two: middleware gives a global baseline, and [RequireHttps] is still useful when a specific endpoint needs a stricter guarantee than the rest of the API.

HSTS

• Strict-Transport-Security is a browser-side instruction, not server-side enforcement: browsers refuse plain-HTTP requests to the host for the duration of max-age, which mitigates SSL-stripping attacks. Non-browser clients (curl, Postman, most mobile HTTP stacks) ignore the header, so HSTS complements redirection and attribute checks but never replaces them.

• Defaults: HstsOptions uses a one-year MaxAge, IncludeSubDomains = false, Preload = false, and ExcludedHosts containing localhost, so localhost responses do not carry the header during development.

Code Example

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = StatusCodes.Status307TemporaryRedirect;
    options.HttpsPort = 443; // set explicitly in production; in dev use the launch port (e.g. 7001)
});
builder.Services.AddControllers();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseHsts(); // skipped in dev to avoid browser-cached HSTS on localhost
}

app.UseHttpsRedirection();
app.UseAuthentication(); // must come before UseAuthorization
app.UseAuthorization();
app.MapControllers();
app.Run();

// Per-endpoint enforcement
[ApiController]
[Route("api/[controller]")]
public class SensitiveController : ControllerBase
{
    // Only this action mandates HTTPS; other actions on the controller do not
    [HttpGet("data")]
    [RequireHttps]
    public IActionResult GetData() => Ok(new { Value = "secure" });
}

Best Practices and Common Pitfalls

• Dev certificates: run dotnet dev-certs https --trust so local HTTPS redirects are not blocked by certificate errors.

• Proxies and load balancers: enable UseForwardedHeaders so the app sees the original scheme; otherwise HTTP-to-HTTPS redirect loops occur behind a TLS-terminating proxy.

• Choose the right tool: middleware for a global policy, a global [RequireHttps] filter for attribute-style enforcement everywhere, and per-endpoint [RequireHttps] only when individual endpoints must differ.

• Testing: verify GET over HTTP returns 307 to https, and that POST over HTTP to a [RequireHttps] action returns 400 rather than being silently redirected.

• HSTS is sticky: once a browser caches the header for max-age, reverting to HTTP is painful for that host, which is why it stays disabled in development.

Core Mechanism

Model binding extracts data from route values, query strings, headers, and the request body. The system uses value providers to locate data and model binders to convert it into .NET types. In Web API, content negotiation determines the formatter used for body binding, typically JSON via System.Text.Json. If conversion fails, the model state becomes invalid, triggering error handling pipelines.

Web API vs MVC Differences

In ASP.NET Core, MVC and Web API share the same underlying model-binding infrastructure. The differences are driven by conventions and the [ApiController] attribute rather than separate engines.

Binding Source Attributes

Developers can override defaults using source-specific attributes. Use [FromBody] to force body binding for simple types or multiple parameters. [FromQuery] binds from the URL query string, and [FromRoute] uses route template values. For Minimal APIs, parameters are inferred automatically unless specified otherwise using explicit attributes or BindAsync.

Validation and Problem Details

When [ApiController] is applied, invalid model state triggers an automatic HTTP 400 response containing Problem Details (RFC 9457). This replaces manual ModelState.IsValid checks. The response format is application/problem+json, including type, title, status, and errors fields. Developers can customize this via AddProblemDetails() in Program.cs.

Common Pitfalls

• Assuming [FromBody] is always required for complex types: with [ApiController] it is inferred automatically.

• Forgetting that [ApiController] also enables attribute routing and automatic 400, so applying it to a view controller can break expected behavior.

• Binding directly to domain entities, which can lead to overposting and mass-assignment vulnerabilities.

Best Practices

• Use DTOs: Bind to dedicated Data Transfer Objects rather than domain entities to prevent overposting.

• Explicit Sources: Mark parameters with [FromQuery] or [FromBody] explicitly for clarity, even if inference works.

• Minimal APIs: Consider Minimal APIs for lightweight endpoints, but use controllers for complex organization.

• Security: Never bind sensitive fields directly; use allowlists or view models.

• Versioning: For API versioning, use the Asp.Versioning.Mvc package; the older Microsoft.AspNetCore.Mvc.Versioning is deprecated.

How Model Binding Works

When a request reaches a controller action, the model binding system inspects the action parameters. For complex types (classes with multiple properties), the default binding source is the request body. The framework uses an input formatter, typically SystemTextJsonInputFormatter in .NET 8, to deserialize the JSON payload into the target object. If the parameter is a simple type (like int or string), the system checks route data and query strings instead.

The request body stream can be read only once, so at most one parameter per action may be bound from the body. Any additional complex parameters must come from other sources such as the query string or route values.

Explicit Binding Sources

While complex types default to [FromBody], you can explicitly specify sources using attributes to avoid ambiguity or combine data from multiple locations. - [FromBody]: Reads from the request body (default for complex types in API controllers). Only one parameter per action may use it. - [FromQuery]: Parses key-value pairs from the URL query string. - [FromRoute]: Extracts values from the route template (e.g., {id}). - [FromForm]: Reads multipart form data, useful for file uploads.

Automatic Validation and Problem Details

With [ApiController], the framework automatically returns a 400 Bad Request response if model validation fails, without requiring manual ModelState.IsValid checks. This response follows RFC 9457 Problem Details format when configured. To enable this globally, register the service in Program.cs using builder.Services.AddProblemDetails(). Controllers can also return custom problem responses using the Problem() helper method, ensuring consistent error serialization across the API.

Note that a null complex-type parameter is not automatically rejected unless validation attributes such as [Required] are applied to the DTO.

Minimal APIs Alternative

In .NET 8, Minimal APIs offer a lightweight alternative where binding occurs directly on the MapPost delegate. Parameters are bound using the same underlying engine, allowing complex types to be declared directly in the lambda signature. TypedResults can be used to maintain explicit HTTP status codes and OpenAPI metadata similar to controller-based approaches.

Best Practices

• Use DTOs: Bind to Data Transfer Objects rather than database entities to prevent overposting and decouple schemas.

• Validate Explicitly: While automatic validation helps, use data annotations like [Required] or [StringLength] on DTO properties.

• Secure Deserialization: Configure JsonOptions to limit deep nesting or excessive payload sizes, which could otherwise lead to denial of service.

• Avoid [FromBody] on GET: GET requests should not have bodies; bind simple types from route or query instead.

Global Configuration

The most common way to change serialization behavior for every controller is to configure JsonSerializerOptions once at startup. In an MVC-style API you call AddJsonOptions on the MVC builder; the same options object is used for both request and response bodies.

• Naming policy: PropertyNamingPolicy = JsonNamingPolicy.CamelCase writes property names as camelCase, matching typical JavaScript conventions.

• Null handling: DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull omits null-valued properties from responses, reducing payload size.

• Reference preservation: ReferenceHandler = ReferenceHandler.Preserve emits $id/$ref metadata so object graphs round-trip correctly, but it changes the JSON shape and should be used only when clients expect it.

• Strictness: AllowTrailingCommas = true and ReadCommentHandling = JsonCommentHandling.Skip make the parser tolerant of commas and comments in incoming JSON.

• Security: MaxDepth limits nesting depth and NumberHandling controls how numbers are parsed, helping to mitigate denial-of-service attacks.

For Minimal APIs there is no MVC builder, so you use ConfigureHttpJsonOptions instead; it configures the same JsonSerializerOptions for the minimal API pipeline.

Per-Type Attributes

When only a few models need special treatment, attributes from System.Text.Json.Serialization avoid global side effects.

• [JsonPropertyName]: renames a single property in the JSON payload, useful when the server name differs from the contract name.

• [JsonIgnore]: excludes a property from serialization entirely, often used for internal fields or write-only values.

• [JsonConverter]: attaches a custom converter to one property or class, overriding the global converter list.

• [JsonExtensionData]: captures unknown JSON fields in a dictionary, enabling forward-compatible APIs that ignore extra fields sent by newer clients.

• [JsonNumberHandling]: controls number parsing and writing per property, for example allowing strings to be read as numbers.

Attributes are ideal for model-specific rules, but they scatter configuration across the domain, so keep them limited to DTOs.

Custom Converters

For formats the built-in serializer does not support—such as a non-standard date string, an immutable type, or a polymorphic discriminator—you implement JsonConverter<T>. It gives full control over Read and Write, letting you parse and format values exactly as required. Converters can be registered globally (so they apply everywhere) or attached to a single type with [JsonConverter]. A typical use case is a DateOnly value that must always appear as yyyy-MM-dd regardless of culture.

Minimal APIs vs Controller-Based APIs

Both styles ultimately configure System.Text.Json, but the entry point differs:

If you mix both in the same app, configure each separately; they do not share options automatically.

Best Practices and Pitfalls

• Prefer global options for cross-cutting concerns such as naming policy and null handling; reserve attributes for model-specific exceptions.

• Keep DTOs separate from domain entities so serialization attributes do not leak into business logic.

• Avoid ReferenceHandler.Preserve in public APIs unless clients understand the $id/$ref metadata; it changes the JSON shape and can break existing consumers.

• Newtonsoft.Json is not deprecated, but it is no longer the default. Use AddNewtonsoftJson() only when migrating legacy contracts or when a feature is missing from System.Text.Json, and plan to move to the built-in serializer.

• Validate payload size and depth with MaxDepth and request-body size limits to prevent denial-of-service from deeply nested or oversized JSON.

• Test round-trips in unit tests: serialize and deserialize your DTOs to ensure renaming or ignoring properties does not silently break clients.

• Document breaking changes when you change naming policy or null handling, because clients may rely on the previous shape.

How It Works

When a request arrives, the framework runs content negotiation against the Accept header (and, for request bodies, the Content-Type header) and asks each formatter, in order, whether it can handle the CLR type in the requested media type.

1. The controller action returns a CLR object (or IHttpActionResult).

2. IContentNegotiator walks config.Formatters and calls CanWriteType / CanReadType on each formatter.

3. The first formatter whose SupportedMediaTypes matches the requested media type and that can handle the type wins.

4. It serializes the object to the response stream (or deserializes the request body into the action parameter).

5. If no formatter matches, Web API returns 406 Not Acceptable for responses (or 415 Unsupported Media Type for request bodies it cannot parse).

Key members of the abstract MediaTypeFormatter base class (in System.Net.Http.Formatting):

• SupportedMediaTypes: collection of MediaTypeHeaderValue objects such as application/json; drives media-type matching.

• SupportedEncodings: encodings (UTF-8, etc.) the formatter can read and write.

• CanReadType(Type) / CanWriteType(Type): queried during negotiation to check whether the formatter handles a given CLR type.

• ReadFromStreamAsync(...): deserializes a request body into an object.

• WriteToStreamAsync(...): serializes an object into the response stream.

• MediaTypeMappings: lets a formatter claim requests based on query-string parameters or URI extensions rather than headers.

Built-in Formatters

The default HttpConfiguration.Formatters collection contains:

Order matters: because JSON is first, a request with Accept: application/json, application/xml gets JSON.

Customizing the Formatter Collection

Common configuration in WebApiConfig:

• JSON-only API: remove XML with config.Formatters.Remove(config.Formatters.XmlFormatter).

• Pretty-printed JSON: config.Formatters.JsonFormatter.Indent = true; (useful for debugging, not production).

• Add a custom format: derive a class from MediaTypeFormatter, override CanWriteType and WriteToStreamAsync, then add it with config.Formatters.Add(...). A client sending Accept: text/csv can then receive CSV for the types your formatter supports, while other accepted types fall back to JSON or XML.

• Browser requests: browsers send Accept: text/html, /, which no default formatter matches; clients get JSON anyway because of the / wildcard, but strict Accept headers can produce a 406.

Best Practices and Common Pitfalls

• Order the collection deliberately: the first matching formatter wins, so add specialized formatters before the generic JSON/XML ones if they should take precedence for overlapping media types.

• Be strict in CanWriteType: returning true for every type can break JSON responses for unrelated controllers.

• Flush and dispose writers correctly: leave the underlying response stream open (the framework owns it) and flush your writer before returning.

• Do not read the request stream twice: a formatter consumes the request body, so a second read in an action filter or model binder will fail.

• Prefer JSON for public APIs: it is the default, is the smallest payload, and is what most clients expect; remove the XML formatter if your API never needs it.

How Content Negotiation Works

When a request arrives, the framework reads the Accept header (honoring quality values such as application/xml;q=0.9) and asks each registered output formatter, in order, whether it can write the returned object for one of the requested media types.

• Match found: the first capable formatter writes the response and sets the matching Content-Type.

• No match: by default MvcOptions.ReturnHttpNotAcceptable is false, so the framework falls back to the first formatter that can serialize the object (normally JSON). Set it to true to return 406 Not Acceptable instead.

• No Accept header or Accept: /: the default formatter (JSON) is used.

Built-in Formatter Options

• JSON: configured with AddJsonOptions on AddControllers() for controller-based APIs, or ConfigureHttpJsonOptions for Minimal APIs.

• XML: added with AddXmlSerializerFormatters (uses XmlSerializer) or AddXmlDataContractSerializerFormatters (uses DataContractSerializer). Both live in the shared framework, so no extra NuGet package is required.

• Minimal APIs: only JSON is negotiated automatically; other formats are produced by returning a custom IResult (for example Results.Text(...) or a hand-written IResult that sets its own media type), which keeps the two programming models distinct.

Adding an Alternative Media Type

For a format that is not built in, derive a class from TextOutputFormatter (text-based formats) or OutputFormatter, add entries to SupportedMediaTypes and SupportedEncodings, override WriteResponseBodyAsync, and register an instance in options.OutputFormatters inside AddControllers(...). Implement the matching TextInputFormatter only if the API must also read that format from request bodies.

Code Example

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers(options =>
    {
        // options.ReturnHttpNotAcceptable = true; // 406 when no formatter matches
        options.OutputFormatters.Add(new CsvOutputFormatter()); // custom media type
    })
    .AddJsonOptions(options =>
    {
        options.JsonSerializer.PropertyNamingPolicy = null; // PascalCase output
    })
    .AddXmlSerializerFormatters(); // registers application/xml formatters

builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();
app.MapControllers();
app.Run();

[ApiController]
[Route("[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id}")]
    [Produces("application/json", "application/xml", "text/csv")]
    public ActionResult<Product> Get(int id)
    {
        return Ok(new Product { Id = id, Name = "Sample" });
    }
}

public class CsvOutputFormatter : TextOutputFormatter
{
    public CsvOutputFormatter()
    {
        SupportedMediaTypes.Add("text/csv");
        SupportedEncodings.Add(Encoding.UTF8);
        SupportedEncodings.Add(Encoding.Unicode);
    }

    protected override bool CanWriteType(Type? type) =>
        typeof(Product).IsAssignableFrom(type) || base.CanWriteType(type);

    public override async Task WriteResponseBodyAsync(
        OutputFormatterWriteContext context, Encoding selectedEncoding)
    {
        var product = (Product)context.Object!;
        await context.HttpContext.Response.WriteAsync(
            $"Id,Name{Environment.NewLine}{product.Id},{product.Name}",
            selectedEncoding);
    }
}

Best Practices and Security

• Prefer JSON for public APIs: smaller payloads and the widest client support across web and mobile platforms.

• Restrict formats per action with [Produces] and document them in OpenAPI; do not enable every format globally.

• XML is safe from XXE by default in .NET 8 because both built-in XML serializers disable DTD processing and external entity resolution; the real risks are oversized or deeply nested payloads, so keep request size limits and reader quotas configured.

• Validate and encode all input before serialization, and never echo unvalidated client data into a custom format such as CSV without escaping delimiters and quotes.

• Classic ASP.NET Web API 2 on .NET Framework 4.8 used global MediaTypeFormatter classes registered in WebApiConfig; ASP.NET Core replaced this with formatters registered per service collection, and the two must not be mixed.

How It Works

DelegatingHandler derives from HttpMessageHandler and adds the InnerHandler property. Handlers are linked in a chain: your handler’s SendAsync runs, calls base.SendAsync(request, cancellationToken) to forward the request to the inner handler, and processes the returned HttpResponseMessage. The innermost handler is HttpClientHandler, which performs the actual network call.

• Single responsibility per handler: each handler does one cross-cutting job (correlation IDs, authentication tokens, retries, logging, compression) and stays independent of controllers and services.

• Ordering matters: handlers execute in registration order on the way out and in reverse order on the way back, so a logging handler registered first wraps everything else.

• Lifetime: handlers added via AddHttpMessageHandler<THandler>() are resolved from dependency injection per HttpClient instance, so they must be stateless or hold only scoped/transient dependencies.

Where They Fit in the Pipeline

Note the asymmetry: in classic Web API 2, DelegatingHandler was the standard way to write inbound cross-cutting concerns; in ASP.NET Core that role belongs to middleware, and DelegatingHandler is the tool for HttpClient calls.

Lifecycle, Ordering, and State

• Chain integrity: every handler must call base.SendAsync unless it deliberately short-circuits (for example, returning a cached response); skipping it breaks the chain and no request is ever sent.

• Per-request state: because handler instances are shared across requests, per-request state must live in HttpRequestMessage.Options (the Properties collection is obsolete in .NET 5+), using an HttpRequestOptionsKey<T>.

• Registration order: register logging first so it measures the full chain, and place retry handlers outside auth-token handlers so a retried request re-evaluates its token.

Best Practices and Common Pitfalls

• Prefer IHttpClientFactory registration over constructing HttpClient or handlers manually, which can lead to socket exhaustion and missed handler lifetime management.

• Do not put business logic in handlers: they are for transport-level concerns; validation and authorization of your own endpoints belong in middleware, filters, or endpoint handlers.

• Keep handlers stateless: they are shared across requests for the lifetime of a handler instance.

• Use async all the way: SendAsync is asynchronous; never block on it with .Result or .Wait().

How the Filter Pipeline Works

ASP.NET Core runs filters in a fixed order for every request:

1. Authorization filters — determine whether the caller may proceed (IAuthorizationFilter).

2. Resource filters — wrap the whole model-binding and action stage (IResourceFilter), useful for caching and short-circuiting.

3. Model binding and action filters — your OnActionExecuting runs, then the action, then OnActionExecuted.

4. Result filters — wrap execution of the returned IActionResult (IResultFilter).

5. Exception filters — handle unhandled exceptions (IExceptionFilter).

Action filters specifically target the action stage; use exception filters for error handling and result filters when you need to modify the serialized response.

Implementing an Action Filter

Deriving from ActionFilterAttribute is the simplest approach because it gives you both hooks as virtual methods:

• OnActionExecuting(ActionExecutingContext context): runs before the action. You can read context.ActionArguments, validate input, modify the arguments dictionary, or short-circuit by assigning context.Result (for example new BadRequestObjectResult(...)), which stops the action from running.

• OnActionExecuted(ActionExecutedContext context): runs after the action. You can inspect context.Result, replace it, or read context.Exception (already handled by an exception filter, so prefer IExceptionFilter for errors).

• Order: set the Order property to control execution sequence when several filters apply; lower numbers run first.

• Multiple applications: whether an attribute can be applied more than once to the same target is controlled by AttributeUsage on the attribute class; the built-in ActionFilterAttribute is already decorated with AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = true, Inherited = true).

Registering and Applying Filters

Three scopes are available, and they compose:

• Global: added in Program.cs with builder.Services.AddControllers(o => o.Filters.Add<MyFilter>()) — applies to every action in the API.

• Controller or action: apply the attribute directly, e.g. [MyLoggingFilter] on a controller class or a single method.

• [ServiceFilter] / [TypeFilter]: use these when the filter needs constructor dependencies. [ServiceFilter] resolves the filter type from the DI container, so you must register it first (builder.Services.AddScoped<MyFilter>()); [TypeFilter] creates it with ActivatorUtilities and can take constructor arguments inline. Both implement IFilterFactory, which is the interface to implement if you write your own attribute-based filter that needs services.

Built-in Alternatives

Before writing a custom filter, check the built-ins: [ResponseCache] (response caching), [Produces]/[Consumes] (content negotiation), [RequireHttps], and the automatic 400 Problem Details validation response that [ApiController] produces for invalid model state. Cross-cutting concerns such as logging, validation, and error mapping are often better expressed as middleware or with IExceptionHandler plus AddProblemDetails(), leaving action filters for logic that genuinely needs the action’s arguments or result.

Code Example

A logging filter applied to a single action, plus a DI-backed filter registered through [ServiceFilter]:

using System.Linq;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.Extensions.Logging;

// Simple attribute filter — no constructor dependencies
public class LogActionFilterAttribute : ActionFilterAttribute
{
    public override void OnActionExecuting(ActionExecutingContext context)
    {
        var args = string.Join(", ", context.ActionArguments.Select(a => $"{a.Key}={a.Value}"));
        Console.WriteLine($"Before {context.ActionDescriptor.DisplayName}. Args: {args}");
        base.OnActionExecuting(context);
    }

    public override void OnActionExecuted(ActionExecutedContext context)
    {
        Console.WriteLine($"After {context.ActionDescriptor.DisplayName}");
        base.OnActionExecuted(context);
    }
}

// Filter that consumes a scoped service via [ServiceFilter]
public class AuditFilter : IActionFilter
{
    private readonly ILogger<AuditFilter> _logger;
    public AuditFilter(ILogger<AuditFilter> logger) => _logger = logger;

    public void OnActionExecuting(ActionExecutingContext context)
    {
        // Short-circuit: assigning a result prevents the action from running
        if (!context.ActionArguments.TryGetValue("id", out var id) || id is not int value || value <= 0)
        {
            context.Result = new BadRequestObjectResult("Id must be a positive integer.");
            return;
        }
        _logger.LogInformation("Audit: request for id {Id}", value);
    }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        if (context.Result is OkObjectResult ok)
            _logger.LogInformation("Audit: returned value {Value}", ok.Value);
    }
}

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet("{id:int}")]
    [LogActionFilter]                       // applied to this action only
    [ServiceFilter(typeof(AuditFilter))]    // resolved from DI
    public ActionResult<string> Get(int id) => Ok($"product-{id}");
}

Registration in Program.cs:

builder.Services.AddScoped<AuditFilter>();              // required for [ServiceFilter]
builder.Services.AddControllers(o =>
{
    o.Filters.Add<LogActionFilterAttribute>();          // global scope
});

Best Practices and Common Pitfalls

• Prefer async over sync: implement IAsyncActionFilter with a single OnActionExecutionAsync method when the filter does I/O; mixing sync and async filters adds thread-pool overhead.

• Keep filters stateless and thread-safe: filter instances may be reused across requests, so never store per-request state in fields.

• Register DI-backed filters as scoped or transient: a singleton filter holding a scoped service causes a captive-dependency bug.

• Don’t swallow exceptions in OnActionExecuted: that is not its purpose; use IExceptionFilter or IExceptionHandler and return RFC 9457 Problem Details.

• Order matters: when combining authorization, validation, and logging filters, set Order explicitly so short-circuiting happens at the intended stage.

Where Each Runs in the Pipeline

ASP.NET Core invokes filters in a fixed order:

1. Authorization filters

2. Resource filters

3. Model binding filters

4. Action filters

5. Exception filters

6. Result filters

Because authorization filters run before model binding, they cannot inspect the bound model or ModelState. Action filters run after model binding succeeds, so they see the validated action arguments and can read or modify them.

Authorization Filters

• Implement IAuthorizationFilter (synchronous) or IAsyncAuthorizationFilter (recommended for async all the way).

• The method OnAuthorizationAsync receives an AuthorizationFilterContext.

• To block a request, set context.Result to an IActionResult such as UnauthorizedResult or ForbidResult; this short-circuits the pipeline so the action never runs.

• The built-in [Authorize] attribute is itself an authorization filter. For most scenarios, prefer policy-based authorization through the authorization service instead of writing a custom filter.

Action Filters

• Implement IActionFilter or IAsyncActionFilter.

• With the synchronous interface, OnActionExecuting runs before the action and OnActionExecuted runs after. With the async interface, call await next() to invoke the action and receive the ActionExecutedContext.

• They can read or modify context.ActionArguments, inspect the result, add response headers, or short-circuit by setting context.Result in OnActionExecuting.

• Typical uses: logging, performance timing, telemetry, adding custom headers, caching metadata.

Comparison

When to Use Each

• Use authorization filters when you need to decide whether a request should be allowed to reach the action—for example, checking authentication, roles, policies, or custom requirements such as tenant validation. They are the correct place for any decision that must happen before model binding and action execution.

• Use action filters when you need to observe or modify the action execution itself: logging entry and exit, measuring execution time, manipulating action arguments, adding response headers, or caching results. They are also appropriate for cross-cutting concerns that should run only after the request has been authorized.

• Never use action filters for security decisions. By the time they run, model binding has already occurred, and an unauthorized request may have already consumed resources or triggered unwanted side effects.

• For most authorization needs, rely on the built-in [Authorize] attribute and policy-based authorization rather than writing a custom authorization filter. Custom authorization filters are rarely needed unless you must inspect the raw request context before the standard authorization system runs.

Best Practices and Common Pitfalls

• Use the async interfaces (IAsyncAuthorizationFilter, IAsyncActionFilter) to avoid thread-pool starvation under load.

• Never put authorization logic in an action filter: it runs too late, after model binding, and bypasses the authorization system.

• Setting context.Result in an authorization filter prevents the action from running entirely; use this deliberately.

• For authorization, prefer [Authorize] with policies over custom filters unless you need low-level context access.

• Apply filters at the right scope: global for cross-cutting concerns, per-controller or per-action with [ServiceFilter] or [TypeFilter] for specific behavior.

• In Minimal APIs, the equivalent concept is endpoint filters via AddEndpointFilter, not MVC action or authorization filters.

How It Works

• AuthenticationHandler<TOptions>: inherit from this class and override HandleAuthenticateAsync() to read credentials and build a ClaimsPrincipal.

• AuthenticationSchemeOptions: a small options class for settings such as the header name to read.

• Scheme registration: AddScheme<TOptions, THandler> adds the handler under a name used by [Authorize(AuthenticationSchemes = "...")].

• Middleware order: app.UseAuthentication() must come before app.UseAuthorization(), otherwise HttpContext.User is never populated.

• Result types: return Success(ticket) for valid credentials, Fail(message) to reject (401), and NoResult() when your handler does not own the request so other schemes can try.

The same scheme also protects Minimal API endpoints via RequireAuthorization(); controller-based and Minimal APIs share the authentication pipeline.

When to Use a Custom Handler

For ordinary token APIs, prefer the built-in JWT bearer scheme; write a custom handler only when built-in schemes cannot express your credential format.

Code Example

public class ApiKeyOptions : AuthenticationSchemeOptions
{
    public string HeaderName { get; set; } = "X-API-Key";
}

public class ApiKeyAuthenticationHandler
    : AuthenticationHandler<ApiKeyOptions>
{
    private readonly IHttpClientFactory _httpClientFactory;

    public ApiKeyAuthenticationHandler(
        IOptionsMonitor<ApiKeyOptions> options,
        ILoggerFactory logger,
        UrlEncoder encoder,
        ISystemClock clock,
        IHttpClientFactory httpClientFactory)
        : base(options, logger, encoder, clock)
    {
        _httpClientFactory = httpClientFactory;
    }

    protected override async Task<AuthenticateResult> HandleAuthenticateAsync()
    {
        if (!Request.Headers.TryGetValue(Options.HeaderName, out var key))
            return AuthenticateResult.NoResult();

        var client = _httpClientFactory.CreateClient("ValidationApi");
        using var request = new HttpRequestMessage(HttpMethod.Get, "/keys/validate");
        request.Headers.Add(Options.HeaderName, key);

        using var response = await client.SendAsync(request);
        if (!response.IsSuccessStatusCode)
            return AuthenticateResult.Fail("Invalid API key");

        var claims = new[] { new Claim(ClaimTypes.Name, key) };
        var identity = new ClaimsIdentity(claims, Scheme.Name);
        var principal = new ClaimsPrincipal(identity);
        var ticket = new AuthenticationTicket(principal, Scheme.Name);

        return AuthenticateResult.Success(ticket);
    }
}

// Program.cs
builder.Services.AddAuthentication("ApiKey")
    .AddScheme<ApiKeyOptions, ApiKeyAuthenticationHandler>("ApiKey", null);

builder.Services.AddHttpClient("ValidationApi", c =>
    c.BaseAddress = new Uri("https://internal-api.example.com"));

builder.Services.AddAuthorization();
builder.Services.AddProblemDetails();
builder.Services.AddControllers();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [Authorize(AuthenticationSchemes = "ApiKey")]
    public ActionResult<IEnumerable<Product>> Get()
        => Ok(Enumerable.Empty<Product>());
}

Best Practices and Pitfalls

• Async all the way: await every I/O call in the handler; never block on async work.

• Reuse HttpClient: obtain clients from IHttpClientFactory; never create new HttpClient() per request.

• Never log secrets: API keys and tokens must not appear in logs or exception messages.

• Enforce HTTPS: credentials travel in headers and require TLS in production.

• Fail vs NoResult: Fail rejects known-bad credentials with 401; NoResult lets other schemes attempt authentication.

• CORS: configure explicitly and never combine AllowAnyOrigin with AllowCredentials.

• Problem Details: with AddProblemDetails(), invalid models return 400 automatically under [ApiController]; use Problem() for custom error responses.

How the Pipeline Is Structured

• Every stage is an HttpMessageHandler. DelegatingHandler is the base class for handlers that hand work off to an InnerHandler, which is what lets handlers form a chain.

• HttpServer is the top-level handler and the entry point of the pipeline. Its default inner handler is HttpRoutingDispatcher, whose inner handler is HttpControllerDispatcher.

• Custom handlers added to HttpConfiguration.MessageHandlers are inserted between HttpServer and HttpRoutingDispatcher, in the order they were registered.

Inbound Stages

1. Host boundary: the host (IIS/ASP.NET through HttpControllerHandler, or self-hosting/OWIN) receives the request and converts it into an HttpRequestMessage.

2. HttpServer: receives the message and starts the handler chain.

3. Custom DelegatingHandler chain: each handler can inspect or modify the request, short-circuit by returning an HttpResponseMessage directly, or call base.SendAsync to continue.

4. HttpRoutingDispatcher: matches the route, populates request.GetRouteData(), and forwards to HttpControllerDispatcher. If nothing matches, a 404 response starts the return journey here.

5. HttpControllerDispatcher: uses IHttpControllerActivator to create the controller and calls IHttpController.ExecuteAsync.

6. Controller pipeline: authentication filters, then authorization filters, then parameter/model binding, then action filters (OnActionExecuting), the action method itself, action filters (OnActionExecuted), and exception filters if an exception propagates. The action returns an IHttpActionResult, an HttpResponseMessage, or a model object that a media-type formatter serializes into the response body.

Outbound Stages

• The HttpResponseMessage produced by the action flows back through the exact same handlers in reverse order; the code after await base.SendAsync(...) in each handler runs on the way out.

• HttpServer is the last stop: it hands the finished response to the host, which writes it to the client.

Key Components

Best Practices and Modern Replacement

• Use handlers only for message-level concerns: handlers see HttpRequestMessage/HttpResponseMessage but no HttpContext, no route data, and no controller context on the way in, so logic that needs routing or the authenticated user belongs in filters, not handlers.

• Mind the registration order: handlers added first execute first on the way in and last on the way out, which matters for concerns such as logging and compression.

• Prefer short-circuiting early: returning a response from a handler skips routing, controller activation, and filters, which is efficient for failures such as an invalid API key.

• Remember this stack is legacy: classic Web API 2 is superseded by ASP.NET Core, where HttpServer and DelegatingHandler are replaced by middleware (InvokeAsync) plus MVC filters; new development should target ASP.NET Core 8 or later.

How It Works

ASP.NET Core is built around DI, so almost every framework component (routing, authentication, options, logging) is resolved from the same container you configure. The flow is:

1. WebApplication.CreateBuilder gives you a WebApplicationBuilder whose Services property is an IServiceCollection.

2. You register each application service with an interface-to-implementation mapping and a lifetime.

3. Framework services are added with extension methods such as AddControllers, AddSwaggerGen, AddProblemDetails, AddAuthentication, and AddCors.

4. At runtime the container constructs your controller, inspecting its constructor and injecting the registered services.

Constructor injection is the preferred form; the container also supports method-level injection in Minimal API route handlers and property injection (via [FromServices]) only for objects the container itself creates.

Service Lifetimes

The lifetime you choose controls how many instances exist and how long they are shared.

Use singleton for stateless or thread-safe shared services (caches, configuration wrappers), scoped for request-scoped work such as Entity Framework DbContext, repositories, and units of work, and transient for lightweight, stateless, short-lived helpers.

Code Example

Registration in Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();                 // [ApiController], model binding, Problem Details
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();                  // .NET 8 template; .NET 9+ uses AddOpenApi()

// Application services, one line per registration
builder.Services.AddSingleton(TimeProvider.System); // .NET 8 time abstraction
builder.Services.AddScoped<IOrderRepository, OrderRepository>();
builder.Services.AddTransient<IEmailSender, SmtpEmailSender>();

// Factory registration when you need to build the instance yourself
builder.Services.AddSingleton<IFeatureFlags>(sp =>
    new FeatureFlags(builder.Configuration.GetSection("Features")!));

// .NET 8 keyed services: register several implementations of one interface
builder.Services.AddKeyedSingleton<ICache, MemoryCache>("local");
builder.Services.AddKeyedSingleton<ICache, RedisCache>("redis");

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthentication();   // must come before UseAuthorization
app.UseAuthorization();
app.MapControllers();
app.Run();

Consumption in a controller-based API:

[ApiController]
[Route("api/[controller]")]
public class OrdersController(IOrderRepository repo, TimeProvider clock) : ControllerBase
{
    [HttpGet("{id:int}")]
    public async Task<ActionResult<Order>> Get(int id, CancellationToken ct)
    {
        var order = await repo.GetAsync(id, ct);
        return order is null ? NotFound() : Ok(order);
    }

    [HttpPost]
    public async Task<ActionResult<Order>> Create(Order order, CancellationToken ct)
    {
        order.PlacedAt = clock.GetUtcNow();
        await repo.AddAsync(order, ct);
        return CreatedAtAction(nameof(Get), new { id = order.Id }, order);
    }

    // .NET 8: pick a specific keyed implementation
    [HttpGet("cached/{id:int}")]
    public async Task<ActionResult<Order>> GetCached(
        int id, [FromKeyedServices("redis")] ICache cache, CancellationToken ct)
        => Ok(await cache.GetOrLoadAsync(id, () => repo.GetAsync(id, ct)));
}

Minimal APIs resolve registered services from the same container, so the two approaches stay consistent:

app.MapGet("/orders", async (IOrderRepository repo, CancellationToken ct)
    => Results.Ok(await repo.ListAsync(ct)));

Best Practices and Common Pitfalls

• Depend on abstractions: register against interfaces so implementations can be swapped or mocked in tests.

• Keep constructors lean: inject only what the class needs; heavy constructors usually signal a class with too many responsibilities.

• Never inject a scoped service into a singleton: the singleton captures it and it stops being request-scoped. If a singleton needs request-scoped work, inject IServiceScopeFactory and create a scope inside the method.

• Avoid the service locator pattern: do not call serviceProvider.GetService<T>() inside controllers or business logic; it hides dependencies and breaks testing.

• Validate registrations in development: builder.Host.UseDefaultServiceProvider(o => { o.ValidateScopes = true; o.ValidateOnBuild = true; }) throws early when a required service is missing or a scope rule is violated.

• Use typed HTTP clients: call other services through AddHttpClient<IWeatherClient, WeatherClient>() so IHttpClientFactory manages handler lifetimes instead of creating a new HttpClient per request.

• Register DbContext as scoped with AddDbContext<T> so each request gets its own context and connections are not shared across concurrent requests.

Classic ASP.NET Web API 2 (for contrast)

In classic ASP.NET Web API 2 on .NET Framework 4.8 there is no built-in container. You add a third-party container (Autofac, Unity, Ninject) and wire it into the pipeline by implementing IDependencyResolver and IDependencyScope and assigning it in WebApiConfig via config.DependencyResolver. The lifetime concepts are the same, but the plumbing is manual and entirely framework-provided in ASP.NET Core.

Unit Test Frameworks

• xUnit: the de facto standard test framework for .NET; supports [Fact] for single-run tests and [Theory] with [InlineData] or [MemberData] for parameterized tests. It integrates with dotnet test, Visual Studio Test Explorer, and CI pipelines.

• NUnit: a mature alternative with a similar attribute-based model ([Test], [TestCase]) and a rich set of constraints.

• MSTest: the Microsoft-supported framework, modernized in .NET 8 with the new Microsoft.Testing.Platform; a good choice for teams already invested in the Microsoft ecosystem.

Mocking and Assertions

• Moq: the most popular mocking library; creates substitutes for interfaces and virtual members so you can test a controller or service in isolation.

• NSubstitute: a friendlier syntax alternative to Moq (Substitute.For<T>(), Received()), often preferred for readability.

• FluentAssertions: replaces the built-in Assert class with chainable, human-readable assertions like response.StatusCode.Should().Be(HttpStatusCode.OK).

• AutoFixture: generates test data automatically, reducing boilerplate in [Theory] tests.

Integration Testing with WebApplicationFactory

• Microsoft.AspNetCore.Mvc.Testing: provides WebApplicationFactory<TEntryPoint>, which hosts your API in-memory using the real middleware, routing, model binding, validation and filters.

• Tests call factory.CreateClient() to get an HttpClient and issue real HTTP requests against the app, receiving full HttpResponseMessage objects.

• Override ConfigureWebHost to swap out services for test doubles, for example replacing a real database context with an in-memory provider or a test database.

• For top-level statement entry points, Program refers to the auto-generated entry-point class; if it is not visible to the test assembly, add [assembly: InternalsVisibleTo("YourTestProject")] to the web project or declare a public partial class Program { }.

Stubbing External Services

• WireMock.Net: stands up a local HTTP mock server to simulate third-party APIs your service calls, so integration tests stay deterministic and offline.

• RichardSzalay.MockHttp: intercepts HttpClient requests in memory; lighter weight than WireMock but only works for requests made through a handler you configure.

Best Practices and Common Pitfalls

• Run unit tests and integration tests in separate projects; integration tests are slower and may need test containers or a real database.

• Never create a new HttpClient per test; reuse the one from CreateClient(), and in production code inject IHttpClientFactory instead of constructing clients directly.

• Keep tests independent and idempotent; clean up test data between runs so tests can execute in any order.

• Prefer testing through the HTTP layer for integration tests rather than calling controller methods directly, which skips middleware, filters and model binding.

• Write async test methods returning Task and avoid .Result or .Wait(), which waste threads and can cause thread-pool starvation.

Core Strategy

• Separate pure business logic into service classes behind interfaces and test those services directly.

• Keep controllers thin: they translate HTTP requests into service calls and service results into HTTP responses.

• Test controllers by instantiating them with mocked dependencies rather than hosting the application.

• For Minimal APIs, test the request delegate by invoking it with a constructed HttpContext; controller-style tests do not apply.

Testing Business Logic

• Call service methods directly with arranged inputs and assert returned values or domain exceptions.

• Mock only external boundaries such as repositories, HTTP clients created through IHttpClientFactory, email senders, or clocks.

• Do not mock the class under test; if a service is hard to test without heavy mocking, it likely has too many responsibilities.

• Use small, real domain objects and fresh fixtures instead of shared mutable state.

Testing Controllers

• Controllers inherit ControllerBase and are marked [ApiController]; model-state validation returns 400 automatically when the action runs through the real pipeline.

• When you instantiate a controller manually, [ApiController] filters do not run, so invalid model state does not automatically produce 400 unless you simulate the filter pipeline.

• Assert the concrete result type: Ok(object) returns OkObjectResult, Ok() returns OkResult, NotFound() returns NotFoundResult, and Problem() returns ProblemResult.

• For ActionResult<T>, inspect both Result for the HTTP status and Value for the payload.

• Prefer Problem() or ValidationProblem() for errors so responses follow RFC 9457 Problem Details.

Unit Tests versus Integration Tests

Best Practices and Common Pitfalls

• Name tests around behavior, for example GetProduct_WhenNotFound_Returns404.

• Keep test methods async Task when awaiting controller actions to avoid deadlocks.

• Never share mutable test state between [Fact] tests.

• Do not assert framework internals such as whether [ApiController] performs model validation.

• Use WebApplicationFactory<T> when you need real HTTP semantics, routing, or authorization; direct controller instantiation is not a replacement for that.

• Depend on interfaces rather than concrete classes so mocks remain lightweight and tests stay focused.

Registration and Dependency Injection

The DbContext must be registered in the service container during application startup in Program.cs. Using AddDbContext configures the context with a database provider — SQL Server via the Microsoft.EntityFrameworkCore.SqlServer NuGet package — and sets the default lifetime to scoped, which aligns with the request scope of a Web API application. Connection strings should be retrieved from configuration rather than hardcoded to maintain security and support different environments.

Controller Design and HTTP Semantics

Controllers should inherit from ControllerBase and be annotated with [ApiController] to enable automatic model validation and attribute routing requirements. Actions must use async and await when calling EF Core methods like ToListAsync or SaveChangesAsync to prevent thread pool starvation. Correct HTTP status codes signal resource state: return 200 for successful GETs, 201 Created with a Location header for successful POSTs, 204 No Content for successful DELETEs, and 404 Not Found when a resource does not exist.

Error Handling with Problem Details

Errors should be returned using the Problem Details format (RFC 9457) via the Problem() method. Configure global problem details behavior using AddProblemDetails in Program.cs if custom conventions are needed. When model validation fails, [ApiController] automatically returns a 400 status with a ValidationProblem response containing the specific validation errors. For business logic failures, such as a conflict during update, explicitly return Conflict() or Problem() with a specific status code to ensure clients receive standardized error payloads. Custom exception filters can centralise this logic across the application.

Code Example

// Program.cs
builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(builder.Configuration.GetConnectionString("DefaultConnection")));

// AppDbContext.cs
public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    public DbSet<Product> Products => Set<Product>();
}

// Product.cs
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
    public decimal Price { get; set; }
}

// ProductsController.cs
[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly AppDbContext _context;

    public ProductsController(AppDbContext context)
    {
        _context = context;
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<Product>> GetProduct(int id)
    {
        var product = await _context.Products.FindAsync(id);
        if (product is null)
            return NotFound();
        return product;
    }

    [HttpPost]
    public async Task<ActionResult<Product>> CreateProduct(Product product)
    {
        _context.Products.Add(product);
        await _context.SaveChangesAsync();
        return CreatedAtAction(nameof(GetProduct), new { id = product.Id }, product);
    }
}

Best Practices and Alternatives

Always query asynchronously and avoid blocking calls like .Result or .Wait() to prevent deadlocks. Use AsNoTracking() for read-only operations to reduce EF Core overhead and improve performance. Ensure migrations are applied via dotnet ef database update or programmatically at startup during development. Minimal APIs are a valid alternative in .NET 8; the table below summarises the trade-offs:

DbContext Lifetime and Registration

• Scoped lifetime: Register the context with AddDbContext<T> so one instance serves each HTTP request; never create it with new or share it across requests.

• DbContext pooling: For high-throughput APIs, use AddDbContextPool<T> to reuse context instances and reduce allocation overhead.

• Connection string: Store it in configuration (appsettings.json or environment variables), never in code.

Query and Save Asynchronously

• Async all the way: Use ToListAsync, FirstOrDefaultAsync, and SaveChangesAsync so threads are not blocked while the database works; pass a CancellationToken through the call chain so work stops if the request is cancelled.

• No tracking for reads: Apply AsNoTracking() on read-only queries to skip change-tracking overhead.

• Projection: Select only the columns you need into a DTO instead of returning whole entities, which also keeps serialization small and stable.

• Controller shape: Expose endpoints with [ApiController] and ControllerBase, returning ActionResult<T>; a POST that creates a resource returns 201 Created with a Location header via CreatedAtAction, while a missing resource returns NotFound().

Avoid Common Pitfalls

• N+1 queries: Load related data eagerly with Include/ThenInclude in one query instead of looping and querying per row.

• DTOs, not entities: Return and accept DTOs so you control serialization and prevent over-posting of navigation properties.

• Short-lived contexts: Do not hold a context open across multiple requests or store it in a static field.

• Transactions: Wrap multiple SaveChangesAsync calls in a transaction via Database.BeginTransactionAsync().

• Migrations: Generate and apply migrations as a deployment step, not at request time.

• Errors: With [ApiController], invalid models return 400 automatically; return NotFound(), Conflict(), or Problem() for other failures so clients receive RFC 9457 problem details.

Performance and Resilience

• Indexes: Ensure foreign keys and frequently filtered columns are indexed in the database.

• Retry logic: Enable SQL Server connection resiliency with EnableRetryOnFailure() for transient faults.

• Bulk operations: For large inserts or updates, consider batching or a bulk extension library rather than one SaveChangesAsync per row.

Following these practices gives an API that scales under load, uses database connections efficiently, and stays secure by design.

How Action Selection Works

When a request arrives, endpoint routing first builds a list of candidate actions from all controllers whose route templates match the URL. Then the action selector narrows that list:

1. HTTP method matching — an action decorated with [HttpGet] only matches GET requests; [HttpPost] matches POST, and so on. Actions without an HTTP method attribute match any verb.

2. Route and constraint matching — [Route] templates and route values (such as an id segment) must align with the request URL, and route constraints like :int further filter candidates.

3. Ambiguity resolution — the selector applies action constraints to disambiguate remaining candidates; if two actions still match indistinguishably, it throws an AmbiguousMatchException rather than guessing.

Key Action Selector Attributes

• [HttpGet], [HttpPost], [HttpPut], [HttpPatch], [HttpDelete], [HttpHead], [HttpOptions]: constrain an action to one HTTP verb. Each accepts an optional template, e.g. [HttpGet("{id:int}")].

• [Route]: sets the URL template for an action or a whole controller. On a controller it acts as a prefix for all its actions.

• [ActionName]: overrides the name used for action selection and link generation, so the method name and the route name can differ.

• [NonAction]: marks a public method that should not be treated as an action (useful for helper methods on a controller).

• [NonController]: marks a class that should not be treated as a controller, even if its name ends in Controller.

Action Result and Status Codes

Selecting the action is only the first half; the return type determines the response. With [ApiController], an invalid model state automatically produces a 400 Bad Request with application/problem+json (RFC 9457) details. A well-shaped API returns 200 OK for reads, 201 Created with a Location header for inserts, 204 No Content for successful deletions or updates that return nothing, 404 Not Found when the resource does not exist, and 409 Conflict for duplicate keys.

Best Practices and Common Pitfalls

• Be specific about verbs: decorating every action with [HttpGet]/[HttpPost] prevents accidental verb overloading and makes the API contract explicit.

• Avoid ambiguous routes: two actions on the same controller with [HttpGet("{id}")] and no distinguishing constraint will collide at runtime — use constraints such as :int or :guid to disambiguate.

• Keep GET, PUT and DELETE idempotent: clients rely on being able to retry these safely; never mutate state irreversibly inside a GET.

• Prefer ActionResult<T>: it gives compile-time type checking for the success case while still allowing error results such as NotFound().

• Minimal APIs are a separate model: endpoint selection there uses MapGet, MapPost, and friends on IEndpointRouteBuilder, with TypedResults for typed results — not attributes on controller classes.

Role in the Request Pipeline

Exception filters implement the IExceptionFilter interface (or IAsyncExceptionFilter for async) and execute only when an unhandled exception bubbles up from a controller action. Unlike the UseExceptionHandler middleware, which wraps the entire request pipeline and can catch errors during routing, startup, or before an endpoint is reached, exception filters are scoped to MVC action execution. This makes them ideal for handling runtime exceptions thrown by actions or MVC-resolved services while still having access to action context such as the route data and action descriptor. You can register them globally via MvcOptions or apply them locally using [ServiceFilter(typeof(GlobalExceptionFilter))], [TypeFilter(typeof(GlobalExceptionFilter))], or a custom attribute class that implements IExceptionFilter.

Integrating Problem Details

Modern APIs should return errors following RFC 9457 (Problem Details, which obsoletes RFC 7807). In .NET 8 you register the supporting services with builder.Services.AddProblemDetails(), which configures the ProblemDetailsFactory and options used by Problem() and ValidationProblem(). Inside an exception filter you construct a ProblemDetails object manually and must set the ContentType to application/problem+json yourself, since a plain ObjectResult would otherwise default to application/json. The payload includes Status, Title, and an optional Detail, letting clients programmatically distinguish error types instead of parsing free-text messages.

Code Example

The following filter captures exceptions, logs them server-side, and returns a 500 Internal Server Error with a RFC 9457 problem details payload.

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;

public class GlobalExceptionFilter : IExceptionFilter
{
    private readonly ILogger<GlobalExceptionFilter> _logger;

    // Resolved from DI when registered via options.Filters.Add<T>()
    public GlobalExceptionFilter(ILogger<GlobalExceptionFilter> logger)
    {
        _logger = logger;
    }

    public void OnException(ExceptionContext context)
    {
        // Log the full exception server-side before returning a generic response
        _logger.LogError(context.Exception, "Unhandled exception occurred");

        var problem = new ProblemDetails
        {
            Status = StatusCodes.Status500InternalServerError,
            Title = "Internal Server Error",
            Detail = "An unexpected error occurred while processing your request."
        };

        context.Result = new ObjectResult(problem)
        {
            StatusCode = problem.Status.Value,
            ContentType = "application/problem+json"
        };
        context.ExceptionHandled = true;
    }
}

Register the filter globally in Program.cs alongside controller services:

builder.Services.AddControllers(options =>
{
    options.Filters.Add<GlobalExceptionFilter>();
});

Best Practices and Pitfalls

• Avoid Sensitive Data: Never expose exception messages or stack traces in the Detail field in production, as this leaks implementation details to potential attackers.

• Logging: Always log the full exception server-side with ILogger<T> before returning a generic response to aid debugging without exposing internals.

• Middleware vs Filters: For comprehensive global handling, UseExceptionHandler middleware is often preferred in .NET 8 because it catches errors outside the MVC pipeline; use filters when you need MVC-specific context like action descriptors or route values.

• Mark Handled: Setting context.ExceptionHandled = true is crucial; otherwise the exception propagates and may trigger default error handling or terminate the request.

• Model State: With [ApiController], invalid model state returns 400 automatically via an action filter before exception filters run, so exception filters focus on runtime exceptions rather than validation errors.

• Async Actions: For async controller actions, prefer implementing IAsyncExceptionFilter with OnExceptionAsync to avoid blocking threads.

How It Works

Every request in ASP.NET Core is handled on a thread from the shared thread pool. When code awaits an I/O-bound operation, the compiler-generated state machine captures the continuation, returns the thread to the pool, and resumes on a pool thread when the operation completes. The key effects are:

• No thread is occupied while waiting for a database query, a remote API, or a file to return.

• The request pipeline is fully asynchronous, so a blocked thread never stalls an earlier middleware stage.

• Scalability improves without raising ThreadPool settings or adding servers: throughput is limited far less by thread count and far more by downstream service capacity.

Key Benefits

• Higher throughput under load: the same hardware serves more concurrent requests, because the fixed pool of threads is not exhausted by waiting work.

• Lower memory and resource pressure: blocked threads each keep a stack and context alive; async requests free those resources during waits.

• Better responsiveness and tail latency: requests are not queued behind long-running synchronous work holding pool threads.

• Natural composition: Task and Task<T> chain cleanly with Task.WhenAll, IAsyncEnumerable, streaming endpoints, and background services.

• First-class framework support: IActionResult, ActionResult<T>, Results, and Minimal API delegates all support async handlers; EF Core, HttpClient via IHttpClientFactory, and file APIs expose async-only or async-preferred methods.

Async Versus Sync: Comparison

Best Practices and Common Pitfalls

• Use async all the way: never mix blocking calls such as .Result, .Wait(), or Task.Delay(...).Wait() into an async path — that causes real deadlocks and pool starvation.

• Prefer async Task<T> over async void, except for fire-and-forget event handlers; async void cannot be awaited and hides exceptions.

• Use CancellationToken in every handler and pass it down to EF Core, HttpClient, and other async APIs so slow clients can be abandoned cleanly.

• Offload genuinely CPU-bound work to Task.Run only when needed, and measure it; async does not make CPU work faster.

• Do not await inside a tight loop when you can batch; use Task.WhenAll for parallel independent calls, but respect downstream rate limits.

• Measure before claiming wins: benchmark with the expected load profile; async mainly helps when requests actually wait on I/O.

How File Upload Binding Works

• IFormFile: Binds a single uploaded file from a multipart/form-data request; the parameter is populated automatically on a matching POST.

• IEnumerable<IFormFile> or IFormFileCollection: Binds multiple files sent under the same form field name.

• [FromForm]: Explicitly marks the source; with [ApiController] it is usually inferred, but adding it makes intent clear.

• Content type: The client must send Content-Type: multipart/form-data; boundary=...; sending application/json will not bind files.

Validating Uploaded Files

Always validate before saving, because the filename and content type come from the client: - Size: Check file.Length against a limit, and also configure FormOptions.MultipartBodyLengthLimit and Kestrel’s MaxRequestBodySize so oversized requests are rejected early with 413. - Content type: Whitelist MIME types (e.g. image/png, application/pdf) rather than trusting the extension. For stronger assurance, inspect the file’s magic bytes after reading. - Filename: Never use file.FileName directly in a path; generate a new name (e.g. a GUID) and append the sanitized extension.

Storing Files Safely

• Stream, don’t buffer: Use await file.CopyToAsync(stream) so large files are not loaded entirely into memory.

• Location: Store outside the web root, or if inside, ensure the folder does not allow script execution. Never store uploads where they can be executed.

• Return semantics: Return 201 Created with a Location header pointing to the stored resource; return 400 for validation failures and 413 Payload Too Large for oversized files. With [ApiController], invalid models already return 400 automatically. Use Problem() or ValidationProblem() to return RFC 9457 Problem Details.

Minimal APIs Alternative

The same upload works in a Minimal API with app.MapPost and an IFormFile parameter, returning Results.Created or TypedResults.BadRequest. Choose controllers when you need attributes, filters and OpenAPI grouping; choose Minimal APIs for simpler endpoints.

Common Pitfalls

• Trusting client filenames enables path traversal; always rewrite the name and combine with a fixed folder.

• Missing size limits lets a client exhaust server memory or disk; set both MultipartBodyLengthLimit and MaxRequestBodySize.

• Returning the file path directly can leak internal structure; return an opaque identifier or a dedicated download URL instead.

• Antivirus scanning: for public-facing uploads, scan stored files before they are served or processed further.

• Blocking the request thread: use async all the way and avoid .Result or .Wait() so upload I/O does not starve the thread pool.

How It Works

SignalR abstracts a persistent connection between client and server and negotiates the best available transport:

On top of the transport, SignalR uses a wire protocol — JSON (the default, via System.Text.Json) or the binary MessagePack protocol — to frame messages. Clients and server exchange messages through a hub, a high-level pipeline that lets server-side code invoke methods on clients and clients invoke methods on the server, without manually managing sockets.

Key Components

• Hub: derive a class from Microsoft.AspNetCore.SignalR.Hub to define server-side methods callable from clients. Hub<T> provides a typed client interface for compile-time safety.

• IHubContext<T>: inject this into controllers, services or background services to push messages to clients from outside the hub itself.

• Clients: property on Hub exposing targets such as All, Others, Caller, User, and Group.

• Groups: named collections of connections, used for topics such as a chat room or a stock ticker symbol.

• ConnectionId / UserId: each connection has an id; authentication tokens identify users so messages can be targeted.

Integration with a Web API

SignalR lives in the same ASP.NET Core pipeline as the API:

1. Add the service with builder.Services.AddSignalR(); add AddMessagePackProtocol() (from the Microsoft.AspNetCore.SignalR.Protocols.MessagePack package) if you need the binary protocol.

2. Map hubs with app.MapHub<THub>("/hubs/...") in the routing configuration.

3. Protect hubs with authentication and authorization — app.UseAuthentication() must come before app.UseAuthorization(), and hubs should carry an [Authorize] attribute.

4. Broadcast from a controller by injecting IHubContext<THub> and calling SendAsync, typically after a POST changes state, so API clients and real-time clients stay consistent.

Code Example

// Hub definition
public class ChatHub : Hub
{
    // Called by clients; server can then push to everyone in the room
    public async Task SendMessage(string room, string user, string text)
    {
        await Clients.Group(room).SendAsync("ReceiveMessage", user, text);
    }

    public override async Task OnConnectedAsync()
    {
        var room = Context.GetHttpContext()!.Request.Query["room"];
        await Groups.AddToGroupAsync(Context.ConnectionId, room!);
        await base.OnConnectedAsync();
    }
}

// Program.cs — registration and endpoint mapping
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSignalR();              // real-time hub infrastructure
builder.Services.AddControllers();          // REST API controllers
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();                    // must precede UseAuthorization
app.UseAuthorization();
app.MapControllers();
app.MapHub<ChatHub>("/hubs/chat");          // hub endpoint beside API routes

app.Run();

// Controller pushing a notification after a state change
[ApiController]
[Route("api/[controller]")]
public class MessagesController : ControllerBase
{
    private readonly IHubContext<ChatHub> _hub;
    private readonly IMessageStore _store;   // app-defined persistence service

    public MessagesController(IHubContext<ChatHub> hub, IMessageStore store)
    {
        _hub = hub;
        _store = store;
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<Message>> Get(int id)
    {
        var message = await _store.GetAsync(id);
        return message is null ? NotFound() : Ok(message);
    }

    [HttpPost]
    public async Task<ActionResult> Post(MessageDto dto)
    {
        var saved = await _store.AddAsync(dto);          // persist first

        await _hub.Clients.Group(dto.Room)               // then notify clients
            .SendAsync("ReceiveMessage", dto.User, dto.Text);

        return CreatedAtAction(nameof(Get), new { id = saved.Id }, saved);
    }
}

Scaling and Best Practices

• Scale-out: a single server holds connection state in memory. With multiple instances, use the Azure SignalR Service (the recommended approach) or a Redis backplane (the Microsoft.AspNetCore.SignalR.StackExchangeRedis package) so messages reach clients connected to other nodes.

• Sticky sessions: required when scaling out with a Redis backplane and WebSockets, so a client’s transport stays on one server; Azure SignalR Service handles routing itself, so sticky sessions are not needed there.

• Authentication: validate tokens on the hub; for browser clients send credentials via cookies or an access token in the query string over HTTPS.

• CORS: configure CORS explicitly for browser clients and never combine AllowAnyOrigin with AllowCredentials.

• Common pitfalls: broadcasting before the data is committed can mislead clients; pushing to Clients.All instead of a group leaks data to unrelated users; long-running work inside a hub method blocks the connection thread and should be offloaded to a service.

Asynchronous Processing

• Async/await: Every I/O-bound operation—database access, file I/O, and downstream HTTP calls—must use async and await so threads return to the pool during waits.

• Avoid blocking: Blocking on tasks with .Result, .Wait(), or .GetAwaiter().GetResult() causes thread pool starvation and collapses throughput under load.

• Return types: Controller actions should return Task<ActionResult<T>> when they await operations; synchronous ActionResult<T> should be reserved for purely in-memory work.

• Middleware: Middleware and hosted services must also follow the async pattern, because one blocked thread reduces the pool available to all requests.

Caching and Compression

• Response caching: Register AddResponseCaching() and apply [ResponseCache] to idempotent GET responses. This lets the server or a reverse proxy serve repeated requests without re-executing business logic.

• Compression: Enable AddResponseCompression() to shrink JSON payloads with Gzip or Brotli. In .NET 8, call UseResponseCompression() before UseRouting() so compression applies to endpoint responses.

• Distributed caching: Use IDistributedCache with Redis or similar for expensive, shared data so repeated requests avoid recomputation and database load.

Data Access and External Calls

• Entity Framework Core: Use AsNoTracking() for read-only queries and project directly to DTOs with Select() to avoid transferring unused columns and change-tracking overhead.

• HTTP clients: Always obtain clients from IHttpClientFactory, preferably as typed clients registered with AddHttpClient<TClient, TImplementation>(). Creating a new HttpClient per request exhausts sockets and degrades latency.

• Cancellation: Keep all data-access and downstream calls asynchronous and propagate CancellationToken so cancelled requests release resources promptly.

Concurrency and Load Protection

• Rate limiting: Use the built-in rate-limiting middleware (AddRateLimiter / UseRateLimiter) with policies such as fixed window, sliding window, or token bucket to prevent a few clients from saturating the service.

• Pagination: Implement pagination (skip/take) with a sensible maximum page size to keep response payloads and query execution time bounded.

• Timeouts: Set reasonable timeouts on database commands and downstream HTTP calls so failures do not hold threads indefinitely.

Payload and Serialization

• System.Text.Json: Rely on System.Text.Json and avoid unnecessary indentation or verbose naming in production; options such as PropertyNamingPolicy and DefaultIgnoreCondition reduce payload size.

• DTOs: Return only the fields the client needs, and prefer 200 OK with small DTOs over full entity graphs.

Observability and Best Practices

• OpenTelemetry: Use OpenTelemetry metrics and tracing to identify real bottlenecks rather than optimizing guesses.

• [ApiController]: Keep [ApiController] enabled so invalid models automatically return 400 Problem Details without manual validation code.

• Middleware ordering: If authentication is used, place UseAuthentication() before UseAuthorization(); this ordering is required and has negligible latency cost.

• Mixed sync/async: Avoid mixing synchronous and asynchronous code paths, and never return large unbounded collections.

Output Caching for Full Responses

Output caching stores the serialized response body and headers so identical subsequent requests skip controller execution entirely. It is enabled with AddOutputCache() in the service collection and UseOutputCache() in the middleware pipeline, then applied per-endpoint with the [OutputCache] attribute or a policy name.

• Base policy: defines the default expiry for all cached endpoints.

• Named policies: add variations such as a short expiry, VaryByQueryKeys, or VaryByHeader.

• Varying: cache separately per query key, header, or a custom WithVaryByValue function so user-specific or locale-specific responses do not collide.

Client-Side and CDN Caching with Headers

For caches outside your server (browsers, reverse proxies, CDNs), set Cache-Control, ETag, and Last-Modified headers. The [ResponseCache] attribute emits these headers, but note that the old response-caching middleware was removed in ASP.NET Core 3.0, so in .NET 8 the attribute only sets headers and performs no server-side storage — output caching is its server-side replacement. For conditional requests, compare the incoming If-None-Match header against a computed ETag and return 304 Not Modified when they match.

Distributed Caching for Application Data

When you cache data rather than full responses, use IDistributedCache, typically backed by Redis via the Microsoft.Extensions.Caching.StackExchangeRedis NuGet package. This survives application restarts and scales across multiple instances, unlike IMemoryCache (registered with AddMemoryCache()), which is per-process. The same IDistributedCache pattern works in Minimal APIs — register it in Program.cs and inject it into the route handler.

Code Example

// Program.cs
// dotnet add package Microsoft.Extensions.Caching.StackExchangeRedis
using Microsoft.AspNetCore.OutputCaching;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(b => b.Expire(TimeSpan.FromMinutes(10)));
    options.AddPolicy("Short", b => b.Expire(TimeSpan.FromSeconds(30)));
});
builder.Services.AddStackExchangeRedisCache(options =>
{
    options.Configuration = builder.Configuration.GetConnectionString("Redis");
});

var app = builder.Build();
app.UseOutputCache();   // register it early, before UseHttpsRedirection, so redirects are not cached
app.MapControllers();
app.Run();

using System.Collections.Generic;
using System.Linq;
using System.Text.Json;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.OutputCaching;
using Microsoft.Extensions.Caching.Abstractions;

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = string.Empty;
}

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private static readonly List<Product> _products =
        new() { new() { Id = 1, Name = "Widget" } };

    private readonly IDistributedCache _cache;

    public ProductsController(IDistributedCache cache) => _cache = cache;

    [HttpGet]
    [OutputCache(PolicyName = "Short")]   // whole response cached for 30 seconds
    public ActionResult<IEnumerable<Product>> Get() => Ok(_products);

    [HttpGet("{id}")]
    public async Task<ActionResult<Product>> GetById(int id)
    {
        var cached = await _cache.GetStringAsync($"product:{id}");
        if (cached is not null)
        {
            var cachedProduct = JsonSerializer.Deserialize<Product>(cached);
            if (cachedProduct is not null) return Ok(cachedProduct);
        }

        var product = _products.FirstOrDefault(p => p.Id == id);
        if (product is null) return NotFound();

        await _cache.SetStringAsync($"product:{id}",
            JsonSerializer.Serialize(product),
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5)
            });
        return Ok(product);
    }
}

Best Practices and Pitfalls

• Cache only safe methods: apply output caching to GET endpoints; POST, PUT and DELETE mutate state and must not be cached.

• Vary by authentication and headers when responses differ per user, otherwise one user may receive another’s cached data.

• Invalidate on writes: expire or remove distributed cache entries when the underlying data changes, or use cache-aside with short expiries.

• Never cache secrets or personalized data without proper vary rules; output caching stores the full response including headers.

• Use HTTPS: cached responses containing sensitive data can leak if transported over insecure connections.

• For development, AddDistributedMemoryCache() avoids needing a Redis server, but switch to Redis before production.

How It Works

• Response envelope: HttpResponseMessage wraps the HTTP status code, response headers, and an HttpContent body. In Web API 2 you return it directly from an ApiController action, often built with the Request.CreateResponse() helper.

• No action-result abstraction: Returning HttpResponseMessage bypasses the IHttpActionResult abstraction, so you lose the Ok()/NotFound() style helpers and take responsibility for building the response yourself. Content negotiation still runs when you assign an ObjectContent<T>; it is skipped only when you assign raw content such as StreamContent.

• Formatter behavior: With ObjectContent<T>, Web API runs the configured formatters (JSON/XML). With StreamContent or PushStreamContent you write bytes directly and avoid serialization overhead entirely.

• Disposable: It implements IDisposable. Web API 2 disposes the response after writing it, but any content you create that wraps a stream or unmanaged resource must be disposed correctly to avoid leaks.

Key Performance Mechanisms

• Streaming large payloads: With PushStreamContent you write directly to the response stream as data becomes available, so a 2 GB file never lives fully in the managed heap. This is the single biggest performance win HttpResponseMessage offers.

• Caching headers: You can set Cache-Control, ETag, and Last-Modified precisely, letting clients and CDNs serve cached copies and reducing server load on repeat requests.

• Avoiding unnecessary negotiation: When the response format is fixed (e.g. a binary download), returning a pre-built ByteArrayContent or stream skips formatter selection.

• Async compatibility: Actions returning Task<HttpResponseMessage> keep threads free during I/O, improving throughput under load.

Web API 2 vs ASP.NET Core .NET 8

In ASP.NET Core on .NET 8, HttpResponseMessage is not supported as a controller action return type: MVC has no output formatter for it, so it would be serialized as a plain object with an unintended 200 status. Use ActionResult<T> / IActionResult with the Ok(), CreatedAtAction(), NoContent() and NotFound() helpers instead. In .NET 8, HttpResponseMessage is the type you consume for outgoing HTTP calls made through IHttpClientFactory.

When to Use It

• Large or unbounded payloads: file downloads, exports, or database blobs that should never be fully materialized in memory.

• Fixed content types: binary or pre-serialized payloads where content negotiation and formatter selection are wasted work.

• Header-level control: cache policy, ETag/If-None-Match handling, range requests, or custom headers that the higher-level helpers do not expose.

• Interoperability with HttpClient: on the client side it is the standard response type for outgoing calls.

Code Example

// ASP.NET Web API 2 (.NET Framework 4.8) - stream a large file without buffering
public async Task<HttpResponseMessage> GetReport(int id)
{
    Stream stream = await _reportService.OpenReportStreamAsync(id);
    var response = Request.CreateResponse(HttpStatusCode.OK);
    response.Content = new StreamContent(stream);
    response.Content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");
    response.Content.Headers.ContentDisposition =
        new ContentDispositionHeaderValue("attachment") { FileName = $"report-{id}.pdf" };
    return response; // Web API disposes the response (and the stream) after writing
}

Common Pitfalls

• Not disposing content: if you create HttpContent that wraps a Stream, ensure it is disposed; a leaked stream pins memory and can exhaust connections.

• Buffering by accident: loading a large file into a byte[] or StringContent before assigning it defeats the streaming benefit and spikes heap usage.

• Returning it from an ASP.NET Core controller: this is not supported in .NET 8 (the object is serialized with a 200 status); use ActionResult<T> instead.

• Blocking on async: always return Task<HttpResponseMessage> and await I/O; calling .Result or .Wait() can cause thread-pool starvation under load.

• Missing cache headers on large static responses: without Cache-Control or ETag, every client re-downloads the full payload, multiplying server work.

Primary Authentication Schemes

How JWT Bearer Authentication Works

1. The client obtains a token from a token endpoint (your API’s login action or an identity provider) by presenting valid credentials.

2. The API validates the token’s signature, issuer, audience, and expiry on each request using middleware registered in Program.cs.

3. Valid tokens populate HttpContext.User; the [Authorize] attribute restricts endpoints. Invalid or missing tokens return 401 Unauthorized, while a valid token lacking required claims or roles returns 403 Forbidden, ideally formatted as RFC 9457 Problem Details (application/problem+json).

Best Practices and Common Pitfalls

• Order matters: UseAuthentication() must run before UseAuthorization(), or [Authorize] sees an empty principal.

• Always use HTTPS in production; tokens sent over HTTP can be intercepted and reused.

• Store secrets outside code: put Jwt:Key, Jwt:Issuer, and Jwt:Audience in user secrets, environment variables, or Azure Key Vault, never committed to source control.

• Keep tokens short-lived (e.g., 15-60 minutes) and use refresh tokens for renewal; long-lived access tokens increase damage if stolen.

• Validate all standard parameters: issuer, audience, lifetime, and signing key. Skipping any of these weakens security.

• Do not mix cookie auth for APIs unless the client is a same-site browser app and you add anti-forgery protection; prefer JWT for mobile and third-party clients.

• Return proper status codes: 401 for missing/invalid tokens, 403 for insufficient claims, and let invalid models return 400 automatically via [ApiController].

How It Works

• Authorization server: authenticates the resource owner and issues access tokens (usually JWT bearer tokens) for a given audience and scope.

• Resource server (your API): validates the token signature, issuer, audience and lifetime, then maps claims to the ClaimsPrincipal.

• Client: requests a token using an OAuth2 grant type (for machine-to-machine APIs typically client_credentials) and sends it as Authorization: Bearer <token>.

• The API never sees passwords and never refreshes tokens; it only accepts and validates access tokens.

Configuring the API

Install the bearer package (dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer), then register authentication before authorization in Program.cs: app.UseAuthentication() must come before app.UseAuthorization(). Configure the handler with the authorization server’s authority (its base URL, which exposes the OIDC discovery document) and this API’s audience, and turn off inbound claim mapping so original JWT claim names like sub and scope are preserved. Define policies that require an authenticated user plus specific scope claims, and add Problem Details so errors follow RFC 9457. With [Authorize], the authentication middleware returns 401 Unauthorized for a missing or invalid token, while a user who is authenticated but lacks the required policy gets 403 Forbidden.

Choosing the Authorization Server

• Entra ID / Azure AD: authority is https://login.microsoftonline.com/{tenant}/v2.0; the audience is your API’s application ID URI, and scopes arrive in the scp claim.

• Duende IdentityServer or OpenIddict: use these when you must host the authorization server yourself. IdentityServer4 is deprecated for current .NET versions — Duende IdentityServer is its supported successor.

• Minimal APIs can apply the same policies with RequireAuthorization("Api.Read") and return TypedResults instead of ActionResult<T>; the authentication/authorization configuration is identical.

Code Example

using System;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = builder.Configuration["Jwt:Authority"]; // authorization server base URL
        options.Audience = builder.Configuration["Jwt:Audience"];   // this API's identifier
        options.MapInboundClaims = false; // keep original JWT claim names (e.g. "sub", "scope")
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidIssuer = builder.Configuration["Jwt:Authority"],
            ValidateAudience = true,
            ValidAudience = builder.Configuration["Jwt:Audience"],
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ClockSkew = TimeSpan.FromSeconds(30)
        };
    });

builder.Services.AddAuthorizationBuilder()
    .AddPolicy("Api.Read", policy =>
        policy.RequireAuthenticatedUser().RequireClaim("scope", "api.read"))
    .AddPolicy("Api.Write", policy =>
        policy.RequireAuthenticatedUser().RequireClaim("scope", "api.write"));

builder.Services.AddProblemDetails(); // RFC 9457 error payloads

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

{
  "Jwt": {
    "Authority": "https://login.microsoftonline.com/<tenant-id>/v2.0",
    "Audience": "api://my-api"
  }
}

using System.Collections.Generic;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private static readonly List<Product> _products = new();

    [HttpGet]
    [Authorize(Policy = "Api.Read")] // requires the api.read scope
    public ActionResult<IEnumerable<Product>> GetAll() => Ok(_products);

    [HttpPost]
    [Authorize(Policy = "Api.Write")]
    public ActionResult<Product> Create(Product product)
    {
        var created = new Product(_products.Count + 1, product.Name);
        _products.Add(created);
        return CreatedAtAction(nameof(GetAll), new { id = created.Id }, created);
    }

    [HttpGet("{id:int}")]
    [Authorize(Policy = "Api.Read")]
    public ActionResult<Product> GetById(int id) =>
        _products.Find(p => p.Id == id) is { } p ? Ok(p) : NotFound();
}

public record Product(int Id, string Name);

Best Practices and Common Pitfalls

• Always validate issuer, audience, lifetime and signing key; AddJwtBearer fetches signing keys from the discovery document, but set ValidIssuer/ValidAudience explicitly.

• Keep ClockSkew small (a few seconds) so expired tokens are actually rejected.

• Require HTTPS and serve the discovery document over HTTPS so keys cannot be tampered with.

• Scope claim names and format vary by IdP: Azure AD uses scp, generic OIDC uses scope, and the value is often one space-separated string, so RequireClaim("scope", "api.read") may not match — use RequireAssertion that splits the value when needed.

• Do not accept any origin with credentials; configure a named CORS policy with an explicit origin list when browsers call the API.

• Use scopes for authorization, not just roles, and keep write scopes separate from read scopes.

• Do not create tokens in the API unless it is also the authorization server; mixing the two roles is a common design mistake.

How It Works

• Issue: The client posts credentials (username/password) to a login endpoint. The server validates them against a store such as ASP.NET Core Identity or a database, then signs a JWT containing claims (user id, roles, expiry) with a secret key and returns it as JSON.

• Send: The client stores the token (securely, e.g. in memory or an httpOnly cookie) and adds it to the Authorization header as Bearer <token> on subsequent calls.

• Validate: The JWT bearer middleware checks the signature, issuer, audience and expiration on each request. If valid, it builds a ClaimsPrincipal for the request.

• Enforce: The [Authorize] attribute on controllers or actions blocks requests without a valid token, returning 401.

Code Example

In Program.cs, register authentication before authorization and configure the bearer scheme; validation parameters must match what the issuer signs with.

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
        };
    });

builder.Services.AddAuthorization();
builder.Services.AddProblemDetails();

var app = builder.Build();

app.UseAuthentication();   // must come before UseAuthorization
app.UseAuthorization();
app.MapControllers();      // registers attribute-routed controllers
app.Run();

The login endpoint validates credentials and returns a signed token; on failure it returns 401, and with [ApiController] invalid model state returns 400 automatically as Problem Details (RFC 9457). Placeholder types and a stubbed validator let the snippet compile.

using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.IdentityModel.Tokens;
using System.Text;

public record LoginRequest(string Username, string Password);
public record TokenResponse(string AccessToken);
public class User { public string Username { get; set; } = string.Empty; }
public class Order { public int Id { get; set; } }

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly IConfiguration _config;

    public AuthController(IConfiguration config) => _config = config;

    [HttpPost("login")]
    public async Task<ActionResult<TokenResponse>> Login(LoginRequest request)
    {
        var user = await ValidateUserAsync(request.Username, request.Password);
        if (user is null)
            return Unauthorized();

        var token = GenerateJwtToken(user);
        return Ok(new TokenResponse(token));
    }

    // Replace with real credential validation, e.g. ASP.NET Core Identity.
    private Task<User?> ValidateUserAsync(string username, string password)
        => Task.FromResult<User?>(new User { Username = username });

    private string GenerateJwtToken(User user)
    {
        var key = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(_config["Jwt:Key"]));
        var credentials = new SigningCredentials(key, SecurityAlgorithms.HmacSha256);
        var token = new JwtSecurityToken(
            issuer: _config["Jwt:Issuer"],
            audience: _config["Jwt:Audience"],
            claims: new[] { new Claim(ClaimTypes.Name, user.Username) },
            expires: DateTime.UtcNow.AddHours(1),
            signingCredentials: credentials);
        return new JwtSecurityTokenHandler().WriteToken(token);
    }

    [Authorize]
    [HttpGet("{id:int}")]
    public ActionResult<Order> GetOrder(int id) => Ok(new Order { Id = id });
}

Protecting Endpoints

Clients send the token in the Authorization header:

GET /api/orders/5
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Apply [Authorize] to controllers or actions; role-based access uses [Authorize(Roles = "Admin")]. Minimal APIs are the alternative to controllers in .NET 8 - protect routes with RequireAuthorization() instead of the attribute, and keep the two styles separate.

Best Practices and Pitfalls

• Never put secrets in code: read Jwt:Key, issuer and audience from configuration or a secrets manager; the key must be at least 256 bits for HS256.

• Use HTTPS everywhere; tokens in transit are bearer credentials anyone can reuse.

• Short-lived access tokens (minutes to an hour) plus refresh tokens reduce theft impact.

• Use UseAuthentication before UseAuthorization; reversing them means authorization never sees the user.

• Prefer ASP.NET Core Identity for user storage instead of rolling your own credential checks.

• Return 401 for missing/invalid tokens and 403 for insufficient claims, not 404 or 500.

• Do not log tokens; they are sensitive credentials.

Client Options

• Browser/SPA apps: JavaScript’s fetch or a library such as Axios calls the API directly over HTTPS.

• Mobile apps: platform HTTP clients (URLSession on iOS, OkHttp/Retrofit on Android, HttpClient in .NET MAUI) call the API, typically with a bearer token from the platform’s secure storage.

• Other .NET services: use HttpClient resolved through IHttpClientFactory — never a new HttpClient() per request, which can exhaust sockets and ignore DNS changes.

• Third-party tools: Postman, curl, or the .NET HTTP REPL are useful for manual testing during development.

How It Works

1. The client locates the API base address (from configuration, service discovery, or an OpenAPI-generated client).

2. It builds an HttpRequestMessage with a method (GET, POST, PUT, DELETE), URI, headers (Authorization, Accept), and an optional JSON body.

3. The API returns a status code: 200 OK, 201 Created with a Location header, 204 No Content, 400 Bad Request with problem details, 401/403, 404, 409, or 500.

4. The client deserializes the JSON response body into strongly typed objects and handles errors explicitly.

.NET Client with IHttpClientFactory

Register a named client with a base address and default headers, then inject IHttpClientFactory where needed. This pools HttpMessageHandler instances, avoiding socket exhaustion and applying Polly policies (retries, circuit breakers) when configured. You can also define a typed client by deriving from HttpClient and registering it with AddHttpClient<T>, which gives you compile-time safety and easier dependency injection.

Best Practices

• Always use HTTPS and validate the API’s TLS certificate; never disable certificate validation in production.

• Send the Authorization header with a JWT bearer token obtained from a trusted identity provider; store tokens in secure storage on the client, never in plain-text config.

• Treat problem details as the error contract: read application/problem+json (RFC 9457) from error responses for machine-readable details.

• Honor idempotency: retry safe methods (GET, PUT, DELETE) on transient failures; avoid blind POST retries or add an idempotency key.

• Respect rate limits: back off when the API returns 429 Too Many Requests, using the Retry-After header.

• Use async end-to-end and pass a CancellationToken so callers can cancel in-flight requests.

• Consider generating clients from OpenAPI (e.g., kiota or other OpenAPI client generators) to keep client models in sync with the API.

Primary .NET Client Options

• HttpClient via IHttpClientFactory: Register clients in dependency injection to avoid socket exhaustion. Use named or typed clients rather than instantiating HttpClient directly.

• Typed Clients: Create a class that wraps HttpClient methods for specific API endpoints, keeping call sites clean and testable.

• Generated Clients: Tools like NSwag produce strongly-typed C# clients from the service’s OpenAPI document, reducing boilerplate and keeping the client in sync with the server.

• Web Clients: JavaScript and TypeScript applications use the native fetch API or libraries like axios for HTTP requests.

HTTP Semantics and Error Handling

Clients must respect HTTP status codes. A successful GET returns 200, while resource creation returns 201 with a Location header. Errors should be parsed as Problem Details (RFC 9457, which obsoletes RFC 7807).

• 200 OK: Successful retrieval or update.

• 201 Created: Resource successfully created; read the Location header for the new resource URI.

• 204 No Content: Successful request with no body, common for DELETE.

• 400 Bad Request: Invalid model or syntax; with [ApiController] this is returned automatically for validation failures.

• 401/403: Authentication or authorization failure.

• 404 Not Found: Resource does not exist.

• 409 Conflict: Concurrency or uniqueness violation.

• 500 Internal Server Error: Unexpected server failure.

When receiving a non-success status, deserialize the content into ProblemDetails to extract Title, Status, and Detail; validation errors are exposed through the Extensions dictionary, or the Errors property on HttpValidationProblemDetails for 400 validation responses, rather than as a top-level Errors field on every problem response.

Authentication and Security

Secure APIs typically require JWT Bearer tokens. Clients must attach the token in the Authorization header using the Bearer scheme.

• Token Storage: Store tokens securely, such as secure HTTP-only cookies server-side or platform-specific secure storage on mobile; never store access tokens in plain-text browser local storage.

• HTTPS: All communication must occur over HTTPS to prevent credential interception.

• CORS: If calling from a browser, the server must explicitly allow the client origin; never combine AllowAnyOrigin with AllowCredentials.

Best Practices and Pitfalls

• Async All the Way: Never block on async calls with .Result or .Wait() to prevent thread-pool starvation and deadlocks.

• HttpClient Lifetime: Do not instantiate HttpClient directly per request; reuse instances managed by the factory.

• Timeouts: Configure Timeout on the client or use cancellation tokens to prevent hanging requests.

• Retry Policies: Use Polly with AddHttpClient for transient fault handling on network calls, with exponential backoff.

• Validation: Validate inputs client-side before sending, but never rely solely on it for security; the server is the authority.

Avoid hardcoding secrets or base addresses in source control; use configuration providers, environment variables, or user secrets for sensitive values.

Understanding Swagger and OpenAPI

• OpenAPI Specification: The language-agnostic standard describing REST APIs in JSON or YAML, formerly known as the Swagger Specification.

• Swagger UI: The interactive interface generated from the OpenAPI document that allows users to try out API endpoints directly.

• Swashbuckle: The specific NuGet package for ASP.NET Core that inspects controllers and attributes to generate the OpenAPI document automatically.

Integration Steps in .NET 8

1. Add the Swashbuckle.AspNetCore package to the project via NuGet.

2. Register the Swagger generator in the dependency injection container using AddSwaggerGen.

3. Add the middleware to the HTTP pipeline with UseSwagger and UseSwaggerUI.

4. Access the documentation at the default /swagger route after launching the application.

Code Example

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
// Register Swagger generator with version info
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

var app = builder.Build();

// Enable Swagger only in development for security
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseAuthorization();
app.MapControllers();
app.Run();

Security and Version Considerations

• Production Security: Restrict Swagger to development environments or protect it with authentication to prevent exposing API structure publicly.

• JWT Support: Configure Swagger UI to send bearer tokens by adding a security scheme in AddSwaggerGen and enabling it in UseSwaggerUI.

• .NET 9 Change: In .NET 9, Microsoft introduced Microsoft.AspNetCore.OpenApi using AddOpenApi() and MapOpenApi(), replacing Swashbuckle in default templates.

Common Causes

A 404 is produced by the routing system when no endpoint matches the request path and method, or by an action that intentionally returns 404. Typical scenarios include:

• Wrong URL path: Typos in the request or in the route template, such as requesting /api/values when the template is /api/products.

• Missing or wrong route attributes: An action without [HttpGet], [HttpPost] or a [Route] template when attribute routing is used, or a mismatch between the template’s literal segments and the request.

• HTTP verb mismatch: Sending GET to an action decorated only with [HttpPost]. With endpoint routing this normally produces 405 Method Not Allowed, not 404, which is a useful diagnostic signal.

• Controllers not mapped: app.MapControllers() is missing from Program.cs, so no controller route is registered at all.

• Resource not found in data: The action executes, looks up the entity by id, and returns NotFound() when it is absent — a correct, expected 404, not a bug.

• Hosting and proxies: A reverse proxy or PathBase misconfiguration strips or rewrites the prefix, so the app receives a path that matches nothing.

Troubleshooting Steps

1. Reproduce the exact request: capture method, path, query string and any proxy hops, so you compare against the real template rather than an assumed one.

2. Inspect the registered endpoints: in .NET 8 the Swashbuckle-based OpenAPI/Swagger UI generated by AddSwaggerGen and UseSwagger lists every route and verb; a route missing there is not registered.

3. Check the route template: verify the controller’s [Route("api/[controller]")] prefix and the action’s [HttpGet("{id}")] segment, including constraints such as {id:int}.

4. Distinguish routing 404 from application 404: set a breakpoint or add logging in the action; if it is hit, the 404 comes from your own NotFound() call, not from routing.

5. Enable routing diagnostics: raise the log level for Microsoft.AspNetCore.Routing in development to see endpoint-matching failure messages.

6. Verify the pipeline order: UseRouting() must run before UseAuthorization() and endpoint mapping, and UseAuthentication() must precede UseAuthorization().

Middleware and Pipeline Checks

The order of middleware in Program.cs determines whether a valid request ever reaches an endpoint.

• Endpoint registration: app.MapControllers() is required for controller-based APIs; minimal APIs register endpoints directly with app.MapGet, app.MapPost and friends.

• Routing first: with explicit UseRouting(), it must come before authorization and mapping so that endpoint metadata (including authorization data) is available.

• Fallback handling: to return RFC 9457 Problem Details (application/problem+json) for genuinely unmatched routes, configure AddProblemDetails() and a fallback endpoint that returns Problem(), rather than leaving a bare empty 404 body.

Best Practices and Pitfalls

• Do not use 404 for validation failures: with [ApiController], invalid model state automatically returns 400 Bad Request; reserve 404 for “no such endpoint” or “no such resource”.

• Return 404 deliberately, not accidentally: look up the entity and return NotFound() when it is missing, and 200 with the payload when it exists; keep that separate from routing failures.

• Prefer attribute routing for APIs: [Route] and verb attributes give explicit, discoverable templates; conventional MapControllerRoute is mainly for MVC views.

• Watch casing in templates: routing matches case-insensitively, but the [controller] token preserves the class name’s casing in the generated URL, so prefer consistent lowercase route literals for predictable generated links.

• Check the verb before blaming the path: a 405 points straight at a verb mismatch, while a 404 points at the path or at endpoint registration.

Versioning Strategies

The version identifier can be carried in three standard places; the choice depends on client constraints and URL preferences. - URI Path: the version is part of the route, e.g. /api/v1/products. Explicit, cache-friendly, and easy for clients and proxies to reason about, but it changes the URL structure between versions. - Query String: the version is appended as ?api-version=1.0. This is the default reader in Asp.Versioning.Mvc, so it works with no extra configuration, but it clutters URLs and can be stripped or logged inadvertently. - Custom Header: the version is sent in a header such as api-version: 1.0. It keeps URLs clean but requires clients to set headers and complicates ad-hoc browser testing. URI path versioning is generally preferred for public APIs because it is visible, self-describing, and plays well with caching and routing tools; query string and header versioning suit internal or legacy clients that cannot change their URLs.

Configuration and Setup

Configuration is a four-step process: register the versioning services, register the API explorer, apply version attributes to controllers, and enable the middleware/UI integration. 1. Add Asp.Versioning.Mvc and Asp.Versioning.Mvc.ApiExplorer from NuGet. 2. Call AddApiVersioning before AddControllers/AddMvc, because the versioning conventions must be applied to the controller application model while it is being built. 3. Set a default version, decide whether an unspecified version resolves to it, and enable version reporting so response headers advertise supported and deprecated versions. 4. Decorate controllers with [ApiVersion] and include {version:apiVersion} in the route template when using URI path versioning.

OpenAPI Integration

Swagger must expose one document per version instead of merging every endpoint into a single list. In .NET 8 the template uses Swashbuckle (AddSwaggerGen/UseSwagger); from .NET 9 the built-in Microsoft.AspNetCore.OpenApi (AddOpenApi/MapOpenApi) replaces it. With Swashbuckle, inject IApiVersionDescriptionProvider, call SwaggerDoc for each ApiVersionDescription (using its GroupName and ApiVersion), and register one SwaggerEndpoint per group in UseSwaggerUI.

Code Example

using Asp.Versioning;
using Asp.Versioning.ApiExplorer;
using Microsoft.AspNetCore.Mvc;
using Microsoft.OpenApi.Models;
using System.Collections.Generic;

// Program.cs - register before AddControllers
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true; // emits api-supported-versions / api-deprecated-versions
});
builder.Services.AddVersioningApiExplorer();
builder.Services.AddSwaggerGen();

// ProductsController.cs
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0", Deprecated = true)]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public ActionResult<IEnumerable<string>> Get() => Ok(new List<string> { "item1" });
}

Best Practices and Common Pitfalls

• Deprecation Policy: mark retiring versions with [ApiVersion("1.0", Deprecated = true)] and publish sunset dates so clients can migrate on a schedule.

• Breaking Changes: never alter an existing version’s contract semantics; ship breaking changes only as a new version and keep the old one working during the deprecation window.

• Response Headers: keep ReportApiVersions enabled so clients receive api-supported-versions and api-deprecated-versions automatically.

• Avoid Over-Versioning: version public, client-facing boundaries; internal microservices that evolve together usually do not need independent versions.

• Cross-Cutting Concerns: apply CORS policies, authentication, and authorization consistently across all versions so a new version does not accidentally bypass security.

• Minimal APIs: the same model applies to Minimal APIs via the Asp.Versioning.Http package, which adds AddApiVersioning and version-aware MapGet/MapPost overloads; keep the two styles distinct, just as controllers return ActionResult<T> while Minimal APIs use TypedResults.

Resource-Oriented Design

• URLs identify resources (nouns), not actions: /api/products/123, not /api/getProduct.

• Use path segments for hierarchy: /api/orders/456/items.

• Let HTTP verbs express the operation: GET retrieves, POST creates, PUT replaces, PATCH partially updates, DELETE removes.

• GET, PUT and DELETE are idempotent; POST is not, so never use POST for reads or GET for writes.

Status Codes and Response Semantics

• 200 OK for successful GET/PUT/PATCH returning a body.

• 201 Created for POST that creates a resource, with a Location header pointing to the new resource.

• 204 No Content for successful DELETE or updates that return nothing.

• 400 Bad Request for invalid input (returned automatically by [ApiController] model validation).

• 401 Unauthorized when unauthenticated, 403 Forbidden when authenticated but not allowed.

• 404 Not Found when a resource does not exist, 409 Conflict for concurrency or uniqueness violations, 500 Internal Server Error for unexpected failures.

Error Responses with Problem Details

• Return errors as application/problem+json per RFC 9457 (which obsoletes RFC 7807) by calling AddProblemDetails() in DI and using Problem() or ValidationProblem() in controllers.

• Include type, title, status, detail and instance; add errors for validation failures. With [ApiController], an invalid model automatically returns 400 as ValidationProblemDetails.

Supporting Practices

• Versioning: use the Asp.Versioning.Mvc package; Microsoft.AspNetCore.Mvc.Versioning is deprecated.

• OpenAPI: .NET 8 templates use Swashbuckle (AddSwaggerGen/UseSwagger); from .NET 9 the built-in Microsoft.AspNetCore.OpenApi (AddOpenApi/MapOpenApi) replaces it.

• Security: JWT bearer or ASP.NET Core Identity, with UseAuthentication before UseAuthorization; configure CORS explicitly and never combine AllowAnyOrigin with credentials.

• Rate limiting: use the built-in middleware (AddRateLimiter, .NET 7+).

• Calling other services: resolve IHttpClientFactory and use named or typed clients; never create new HttpClient() per request, and use async all the way.

Common Pitfalls

• Returning 200 for errors or 500 for client mistakes, which breaks client error handling.

• Using verbs in URLs or a single POST endpoint for every operation.

• Creating new HttpClient() per request, which exhausts sockets under load.

• Returning plain-text errors instead of Problem Details, making errors hard to parse.

• Allowing any origin while sending credentials over CORS, which browsers reject.

Authentication and Authorization

• Missing or weak authentication: Endpoints with no authentication requirement are open to the internet. Apply AddAuthentication().AddJwtBearer(...) and AddAuthorization(), and place UseAuthentication() before UseAuthorization() in the pipeline — the order matters, because authorization needs an authenticated ClaimsPrincipal.

• Confused authorization logic: Role checks hard-coded in action bodies drift out of sync with policy requirements. Prefer [Authorize(Policy = "...")] with named policies defined in AddAuthorization, so access rules live in one place.

• Over-posting / mass assignment: Model binding can populate properties the client should not control. Use [BindNever] on sensitive properties or bind to a dedicated DTO rather than your entity directly.

• Insecure token handling: Accept tokens only over HTTPS, validate the issuer, audience, lifetime, and signature, and never store long-lived secrets in the browser.

Transport and Cross-Origin Security

• Plain HTTP: Without TLS, credentials, tokens, and personal data are visible on the wire. Require HTTPS, and in production enable HSTS (UseHsts) plus HTTP-to-HTTPS redirection (UseHttpsRedirection).

• Mixed or expired certificates: A valid certificate is part of the trust chain; expired or self-signed certs in production break clients and can silently downgrade trust.

• Misconfigured CORS: Configure CORS explicitly with a named policy, and never combine AllowAnyOrigin() with AllowCredentials() — that combination is explicitly disallowed by the browser and signals a broken design.

Input Validation and Injection

• Unvalidated input: Never trust query strings, route values, or bodies. With [ApiController], invalid models automatically return a 400 with Problem Details (application/problem+json, RFC 9457), so annotate DTOs with validation attributes and let the pipeline enforce them.

• SQL injection: Always use parameterized queries or an ORM such as EF Core. Never concatenate user input into raw SQL.

• Overly permissive model binding: Bind only the properties you need, and reject unexpected fields rather than silently ignoring them.

Business Logic and Abuse

• No rate limiting: A login or password-reset endpoint without throttling invites brute force and credential stuffing. Use the built-in AddRateLimiter middleware (.NET 7+) with per-endpoint or per-user limits.

• Insecure direct object references (IDOR): Just because a request is authenticated does not mean the caller may read or write any record. Authorize against the resource owner on the server, e.g. verify the order belongs to the current user before returning it.

• Missing audit trails: Security incidents are impossible to investigate without logs. Log authentication failures, authorization denials, and state-changing operations — but never log secrets or tokens.

Secrets, Configuration and Best Practices

• Hard-coded secrets: Connection strings, API keys, and JWT signing keys belong in the secret store (User Secrets locally, Azure Key Vault or an equivalent in production), never in source control.

• Weak signing keys: Generate a long, random key for JWT signing; do not reuse a short or shared secret across services.

• Fail closed: When authorization data is missing or ambiguous, deny access rather than allowing it.

• Return generic errors to clients: Use Problem Details for consistent 400/401/403/404/409/500 responses, and keep stack traces and internal details in server logs only.

• Keep packages current: Vulnerable dependencies are a leading cause of breaches; scan and update NuGet packages regularly.

• Test the negative paths: Verify that forbidden requests return 401 or 403, not the data.

Strengths That Drive the Choice

• Mature HTTP and REST semantics: first-class support for verbs, content negotiation, status codes (200 OK, 201 Created with a Location header, 204 No Content, 400/404/409/500), and RFC 9457 Problem Details via AddProblemDetails() and Problem() / ValidationProblem().

• Cross-platform hosting: runs on Windows, Linux, and macOS in Kestrel, IIS, or containers — unlike classic ASP.NET Web API 2, which is tied to .NET Framework 4.8 and Windows/IIS.

• Strong typing and tooling: controllers returning ActionResult<T>, automatic model validation with [ApiController], and OpenAPI generation (Swashbuckle AddSwaggerGen/UseSwagger in the .NET 8 template; the built-in Microsoft.AspNetCore.OpenApi package with AddOpenApi/MapOpenApi from .NET 9).

• Unified security stack: JWT bearer authentication, ASP.NET Core Identity, CORS, and the built-in rate limiter (AddRateLimiter, .NET 7+) compose into the same pipeline, with UseAuthentication before UseAuthorization.

• Performance and ecosystem: high-throughput, low-allocation runtime, plus NuGet libraries for API versioning (Asp.Versioning.Mvc — the replacement for the deprecated Microsoft.AspNetCore.Mvc.Versioning), Entity Framework Core, IHttpClientFactory for outbound calls, and gRPC endpoints side-by-side.

When It Fits Best

• Public or partner APIs consumed by browsers and mobile apps, where REST + JSON, OpenAPI docs, and explicit versioning matter.

• Backends for modern front ends (SPA, Blazor, Xamarin/.NET MAUI, native iOS/Android) that need token-based auth and clean resource-oriented endpoints.

• Microservices and containerized workloads on Linux/Kubernetes, where cross-platform, small footprint images, and cloud-native telemetry are required.

• Complex, policy-rich services where you want full control over filters, model binding, action results, and middleware — areas where controller-based APIs shine.

When to Prefer an Alternative

Decision Guidance

• If the consumer is a browser or mobile app speaking JSON over HTTPS, ASP.NET Core Web API is the default recommendation on .NET.

• If the workload is internal, RPC-style, and latency-critical, evaluate gRPC first — you can host both in the same app.

• If the service is tiny and stable, start with Minimal APIs; migrate to controllers if cross-cutting concerns grow.

• If you are maintaining an existing Web API 2 solution on .NET Framework 4.8, plan a migration to ASP.NET Core rather than new WCF/SOAP development.

Common Pitfalls

• Mixing generations: classic Web API 2 (WebApiConfig, IHttpActionResult, Global.asax) cannot be combined with ASP.NET Core 8 patterns; migration is a rewrite of the hosting layer.

• Ignoring idempotency: treat GET, PUT, and DELETE as idempotent and reserve POST for non-idempotent creation.

• Weak CORS: never allow all origins together with credentials; configure explicit allowed origins.

• Blocking calls: use async/await end to end and IHttpClientFactory — never instantiate HttpClient per request.

Scale Out and Keep Requests Non-Blocking

• Keep servers stateless: store session or user state in a distributed store (Redis, a database, or tokens issued to the client) rather than in-process memory or HttpContext.Session. Any instance can then serve any request, which is what load balancers and container orchestrators need to add or remove replicas.

• Prefer externalizing all shared state: distributed cache, distributed rate-limit counters, and a shared data store must live outside the process if you scale out.

• Avoid sticky sessions: they limit a load balancer’s ability to redistribute traffic and make rolling deployments slower.

• Use async/await end to end and never call .Result or .Wait() on a Task, which can deadlock or exhaust the thread pool.

• Call downstream HTTP services through IHttpClientFactory (named or typed clients) so sockets are reused; creating a new HttpClient() per request causes socket exhaustion under load.

• Offload long-running work to a queue plus a background service (IHostedService/BackgroundService, or a real message broker such as Azure Service Bus, RabbitMQ, or Kafka) and return 202 Accepted immediately.

Reduce the Work per Request

• Cache aggressively: IMemoryCache for single-instance data, IDistributedCache (Redis) for shared data, and response/output caching for expensive GET responses.

• Paginate and project: return only the fields and rows clients need; never return an unbounded collection from a GET endpoint.

• Compress responses: built-in response compression middleware reduces bandwidth for JSON payloads.

• Use efficient serialization: System.Text.Json is the default and is faster than Newtonsoft.Json for most workloads.

Protect the API Under Load

• Apply the built-in rate limiting middleware (AddRateLimiter, .NET 7+) with sensible per-client or per-user policies, and return 429 Too Many Requests with a Retry-After header.

• Use concurrency limiting (e.g. a SemaphoreSlim or a queue-based pattern) for endpoints that hit scarce resources.

• Configure CORS explicitly; never combine AllowAnyOrigin with AllowCredentials.

• Secure endpoints with JWT bearer authentication or ASP.NET Core Identity, and order the pipeline UseAuthentication() before UseAuthorization().

Scale the Data Tier

The API is usually only as scalable as its data store, so treat database scaling as part of the design.

Keep the Contract Stable and Observable

• Version the API with the Asp.Versioning.Mvc package (Microsoft.AspNetCore.Mvc.Versioning is deprecated); URI or header versioning keeps changes from breaking existing clients.

• Return errors as Problem Details (application/problem+json, RFC 9457) via AddProblemDetails() and Problem()/ValidationProblem(), so clients get a consistent, machine-readable error shape.

• Emit structured logs, metrics, and distributed tracing, and define health checks (AddHealthChecks) so the platform can route traffic only to healthy instances.

• Generate OpenAPI documents (Swashbuckle AddSwaggerGen/UseSwagger in .NET 8; the built-in Microsoft.AspNetCore.OpenApi package from .NET 9) so clients and tooling can evolve with the API.

Best Practices and Common Pitfalls

• Choose controller-based APIs with [ApiController] and ActionResult<T> for complex, policy-driven APIs; choose Minimal APIs with TypedResults for smaller, low-ceremony services — keep the two styles distinct within a single project.

• Watch out for hidden state: in-process caches, static collections, and IDistributedCache-less rate limiters all break under scale-out.

• Load test before assuming a design scales; most bottlenecks are the database or a downstream service, not the web tier.

Core Characteristics

• Independent deployability: each service has its own CI/CD pipeline and can be released without redeploying the rest of the system.

• Bounded contexts: a service models one business capability (e.g. Ordering, Catalog, Identity) and exposes only the APIs that capability needs.

• Decentralized data: each service owns its database; there is no shared schema. Services exchange data through APIs or events, never through cross-service database joins.

• Polyglot technology: because services communicate over standard protocols, individual teams can choose the store or runtime that fits their service.

• Elasticity and resilience: instances can be scaled horizontally per service, and failures are contained by retries, circuit breakers and timeouts.

Service Design with ASP.NET Core Web API

Each service is a standard Web API project using the controller style with [ApiController] and ControllerBase, returning ActionResult<T> or IActionResult. Minimal APIs with TypedResults are a valid lighter alternative for small services, but the two styles should not be mixed within one service.

• HTTP semantics: GET, PUT and DELETE are idempotent; POST creates resources and is not idempotent. A successful creation returns 201 Created with a Location header; idempotent deletes or updates return 200 OK or 204 No Content.

• Error contracts: errors are returned as Problem Details (application/problem+json, RFC 9457, which replaces RFC 7807) via AddProblemDetails() and Problem() / ValidationProblem(). With [ApiController], an invalid model automatically produces a 400 with a validation problem response.

• API versioning: use the Asp.Versioning.Mvc package; Microsoft.AspNetCore.Mvc.Versioning is the deprecated predecessor.

• API documentation: on .NET 8 the project template uses Swashbuckle (AddSwaggerGen / UseSwagger); from .NET 9 the built-in Microsoft.AspNetCore.OpenApi (AddOpenApi / MapOpenApi) replaces it.

Communication Patterns

• Outbound HTTP calls go through IHttpClientFactory as named or typed clients — never a new HttpClient() per request — and are fully async to avoid blocking threads.

• Service-to-service discovery is handled by a gateway, reverse proxy or container orchestrator service registry rather than hard-coded host names.

Cross-Cutting Concerns

• API gateway: routes external traffic, aggregates responses, terminates TLS and applies shared policies, so individual services stay focused on business logic.

• Authentication and authorization: JWT bearer tokens issued by an identity service (or ASP.NET Core Identity); the pipeline calls UseAuthentication() before UseAuthorization().

• CORS: configured explicitly per known origin; never combine AllowAnyOrigin with AllowCredentials.

• Rate limiting: the built-in AddRateLimiter middleware (.NET 7+) applies per-client or per-endpoint quotas.

• Observability: structured logging, metrics and distributed tracing with a correlation ID propagated across service hops.

• Resilience: Polly-based retries and circuit breakers for outbound calls, plus per-service health checks exposed for orchestrator probes.

Advantages and Limitations

Microservices improve team autonomy, independent scaling and technology diversity, but they add operational cost: distributed transactions become sagas or outbox patterns, testing spans multiple deployments, and network latency and partial failures must be designed for from the start. A common pitfall is splitting services too finely (“nanoservices”), which turns a monolith’s in-process calls into expensive remote hops.

Best Practices

• Model service boundaries on business domains, not database tables or layers.

• Keep one data store per service and publish integration events for cross-service data changes.

• Prefer asynchronous events for anything that does not need an immediate response.

• Version APIs from day one and treat the published contract as a public API.

• Deploy and monitor each service independently, and automate the full pipeline before adding more services.

Core Concept

The pattern defines a contract, usually an interface like IProductRepository, which declares methods for data operations such as retrieval, insertion, or deletion. Concrete classes implement this contract by executing queries against a database context, typically Entity Framework Core. This separation ensures that high-level modules (controllers) do not depend on low-level modules (database details), adhering to the Dependency Inversion Principle and facilitating cleaner architecture.

Dependency Integration

ASP.NET Core includes a built-in Dependency Injection container configured in Program.cs. Repositories are registered as scoped services, meaning one instance is created per HTTP request. This aligns perfectly with the DbContext lifetime, preventing captive dependency issues where a transient service holds a reference to a scoped context. The framework automatically injects the registered implementation into any controller constructor requesting the interface.

Controller Implementation

Controllers inherit from ControllerBase and are marked with [ApiController] to enable automatic model validation and attribute routing requirements. Actions accept the repository interface via constructor injection and return ActionResult<T>. This return type allows precise HTTP status codes, such as returning NotFound() when a record is missing or Ok() with the entity when successful, ensuring clients receive semantically correct responses.

Architecture Considerations

While beneficial, introducing a repository layer over Entity Framework Core can sometimes add unnecessary indirection, since DbContext already implements Unit of Work and Repository behaviors. Custom repositories are most valuable when encapsulating complex queries, sharing data logic across multiple services, or abstracting non-relational data sources. For simple CRUD scenarios, Minimal APIs with direct DbContext access might reduce boilerplate while maintaining clarity.

Code Example

public interface IProductRepository
{
    Task<Product?> GetByIdAsync(int id, CancellationToken ct);
    Task AddAsync(Product product, CancellationToken ct);
}

public class ProductRepository : IProductRepository
{
    private readonly AppDbContext _context;
    public ProductRepository(AppDbContext context) => _context = context;

    public async Task<Product?> GetByIdAsync(int id, CancellationToken ct)
        => await _context.Products.FindAsync(id, ct);

    public async Task AddAsync(Product product, CancellationToken ct)
    {
        _context.Products.Add(product);
        await _context.SaveChangesAsync(ct);
    }
}

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IProductRepository _repository;
    public ProductsController(IProductRepository repository) => _repository = repository;

    [HttpGet("{id}")]
    public async Task<ActionResult<Product>> Get(int id)
    {
        var product = await _repository.GetByIdAsync(id, HttpContext.RequestAborted);
        return product is null ? NotFound() : Ok(product);
    }
}

// In Program.cs
builder.Services.AddScoped<IProductRepository, ProductRepository>();

Best Practices and Pitfalls

• Service Lifetime: Register repositories as Scoped to match DbContext. Transient repositories accessing scoped contexts can cause concurrency and disposal exceptions.

• Async All the Way: Ensure every method in the chain is async to avoid thread pool starvation under high concurrency.

• Avoid Anemic Repositories: Do not create repositories that merely pass through single DbContext calls; this adds maintenance cost without architectural benefit.

• Unit Testing: Mock the repository interface to test controller logic in isolation without requiring a live database connection.

What OWIN Is

• Specification: OWIN is an open specification (owin.org) that describes a delegate signature between server and application: Func<IDictionary<string, object>, Task>. The dictionary carries the request, response, headers, and environment state.

• Katana: Microsoft’s implementation of OWIN is called Katana, shipped as the Microsoft.Owin.* NuGet packages.

• Middleware: An OWIN middleware component is a function that receives the environment dictionary and a next delegate. It can handle the request itself (short-circuit) or call await next() to pass it down the pipeline.

How Web API Uses the OWIN Pipeline

• In classic Web API 2, the framework normally runs on the IIS integrated pipeline through System.Web. OWIN hosting lets you run the same HttpConfiguration and routes outside IIS, or insert Web API into a custom OWIN pipeline.

• You create a Startup class with a Configuration(IAppBuilder app) method, build an HttpConfiguration, register routes with config.Routes.MapHttpRoute, and wire Web API into OWIN with app.UseWebApi(config).

• The order of app.Use... calls defines the middleware order: authentication and CORS middleware typically run before UseWebApi, so they can reject unauthorized requests before routing reaches a controller.

Typical Middleware Components

• Authentication: Microsoft.Owin.Security packages (OAuth bearer tokens, cookies) validate tokens and set the user principal before Web API runs.

• CORS: Microsoft.Owin.Cors enables cross-origin requests with app.UseCors.

• Error handling: Custom middleware can catch exceptions and write a consistent error response.

• Logging and diagnostics: Middleware can log request paths, durations, and response status codes.

OWIN Hosting vs System.Web Hosting

Best Practices and Deprecation Notes

• OWIN and Katana are legacy and no longer actively developed. For new HTTP services, use ASP.NET Core on .NET 8, which has a built-in, higher-performance middleware model (IApplicationBuilder, HttpContext, RequestDelegate) and does not use OWIN.

• If you maintain an existing OWIN-hosted Web API, keep middleware ordered deliberately: diagnostics and exception handling first, then authentication and CORS, then UseWebApi.

• When OWIN middleware calls downstream HTTP services, do not create a new HttpClient per request — that exhausts sockets; reuse a single long-lived HttpClient (or a small set of preconfigured instances) and stay async all the way.

• ASP.NET Core provides Microsoft.AspNetCore.Owin as a compatibility adapter if you must interoperate with OWIN components during migration, but new code should target the ASP.NET Core middleware pipeline.

OpenAPI Generation with Swashbuckle

The .NET 8 Web API template includes the Swashbuckle.AspNetCore NuGet package. Register the generator with builder.Services.AddSwaggerGen(), then expose the specification and UI with app.UseSwagger() and app.UseSwaggerUI(). By default, UseSwagger() serves the JSON document at /swagger/v1/swagger.json, and UseSwaggerUI() hosts the interactive UI at /swagger. Starting with .NET 9, the template moves to the built-in Microsoft.AspNetCore.OpenApi package using AddOpenApi() and MapOpenApi(); Swashbuckle remains supported but is no longer the default.

Enriching Metadata

Raw reflection discovers routes and basic schemas, but useful documentation needs explicit metadata:

• XML comments: Add /// comments to controllers and actions, then load them with c.IncludeXmlComments(xmlPath); otherwise Swashbuckle does not import them.

• Response declarations: Use [ProducesResponseType(typeof(MyModel), StatusCodes.Status200OK)] on controller actions so the UI documents accurate status codes and response bodies.

• Minimal APIs: Call Produces<T>() and Accepts<T>() on the RouteHandlerBuilder to supply the same schema information.

Security and Environment Considerations

Do not leave documentation exposed in production. The common pattern is to register Swagger services in all environments but enable the middleware only when app.Environment.IsDevelopment() returns true. If documentation must be reachable externally, protect it with an authentication policy and never combine AllowAnyOrigin() with AllowCredentials() in CORS configuration.

Code Example

using System.IO;
using System.Reflection;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    // Load the XML comments produced by the build
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

var app = builder.Build();

// Expose the OpenAPI document and UI only in Development
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.Run();

Best Practices and Pitfalls

• API versioning: When using the Asp.Versioning.Mvc package, configure Swagger to emit a separate specification per version instead of merging all versions into one document.

• Sensitive data: Never hardcode secrets, connection strings, or internal addresses in XML comments, example factories, or schema filters.

• Metadata drift: Keep XML comments and [ProducesResponseType] declarations synchronized with code; stale documentation is worse than none.

• Minimal APIs: AddEndpointsApiExplorer() is required for minimal API endpoint discovery; it is optional for controller-based APIs.

• Version awareness: On .NET 9 and later, prefer AddOpenApi() / MapOpenApi() unless you need Swashbuckle-specific UI features.

How Conventional Routing Works

• Registration happens in Program.cs through MapControllerRoute, which is an extension on IEndpointRouteBuilder (available on the WebApplication instance built by WebApplication.CreateBuilder).

• A route template mixes literal segments with parameters in braces, for example api/{controller}/{id?}.

• The routing middleware evaluates registered templates in the order they were added; the first template whose pattern matches the request path wins.

• The matched route values are used to locate the controller by appending “Controller” to the {controller} segment, to choose the action method, and to supply action parameters.

• When the template does not include an {action} segment, the action name is inferred from the controller method name, and the HTTP verb is matched by action selector attributes such as [HttpGet] or [HttpPost]; the verb alone does not pick the action.

Conventional Routing Compared with Attribute Routing

Route Constraints and Model Binding

• Inline constraints such as {id:int} or {slug:alpha} validate a segment before the route is considered a match, preventing invalid values from reaching the action.

• Constraints also disambiguate overlapping routes, for example separating numeric IDs from string slugs.

• Model binding automatically converts matching route values to action parameters with the same names, performing type conversion and reducing manual parsing.

• If a constraint fails, routing continues to the next template rather than invoking the action.

Best Practices and Common Pitfalls

• Prefer attribute routing for public-facing APIs because it gives explicit control over URIs and works cleanly with API versioning packages such as Asp.Versioning.Mvc.

• Use conventional routing for internal microservices or simple endpoints where a stable, predictable URL pattern is sufficient.

• Do not mix conventional and attribute routing inside the same controller unless you understand the precedence rules; attribute routes win.

• Always apply constraints to route parameters to reject malformed input early.

• Remember to call builder.Services.AddControllers() so controllers are discovered; if you also use attribute routing, call app.MapControllers() in addition to any MapControllerRoute calls.

• For very lightweight endpoints, consider Minimal APIs with MapGet/MapPost and TypedResults, which bypass controller routing conventions entirely.

Core Limitations

Convention-based routing relies on a single global template registered in Program.cs, such as {controller=Home}/{action=Index}/{id?} or an API-specific api/{controller}/{action=Index}/{id?}. This creates several drawbacks: - URL coupling: The URL is derived from the controller and action names, so renaming a class or method breaks the public contract unless the global template is changed. - Verb ambiguity: Without explicit verb attributes, multiple actions on one controller can match the same HTTP method and route, producing ambiguous-match errors or unexpected selection. - Versioning difficulty: Embedding version segments such as /api/v1/products requires extra template tokens or per-controller overrides rather than a declared version policy. - Hierarchy constraints: Nested resources such as /customers/{customerId}/orders do not map cleanly onto a flat {controller}/{action} structure and often force awkward action naming. - Implicit surface: Every public action method is potentially routable unless explicitly excluded, which makes it harder to reason about the exposed API surface.

Attribute Routing

Attribute routing lets developers define routes directly on controllers and actions with [Route], [HttpGet], [HttpPost] and the other verb attributes. This decouples the physical class structure from the public API surface and supports optional parameters, constraints, default values and explicit HTTP method mapping, so each endpoint has a unique, predictable signature. It is the standard approach for [ApiController]-based controllers in ASP.NET Core, and route templates can be combined at controller and action level (for example [Route("api/v1/[controller]")] with [HttpGet("{id:int}")]).

Minimal APIs

Minimal APIs define routes directly in Program.cs with methods such as MapGet, MapPost, MapPut and MapDelete, using lambda handlers instead of controller classes. This removes boilerplate, keeps route definitions and handlers in one place, and fits small services or microservices well. They support TypedResults for strongly typed, OpenAPI-friendly responses, and in .NET 8 they integrate with Swashbuckle (AddSwaggerGen/UseSwagger), which the template ships by default; from .NET 9 the built-in Microsoft.AspNetCore.OpenApi (AddOpenApi/MapOpenApi) replaces Swashbuckle.

Comparison

Best Practices and Pitfalls

• Do not blend models: A controller that has attribute routes cannot also be reached by convention routing — its unattributed actions are simply not routable. Pick one model per controller.

• Version by policy: Use the Asp.Versioning.Mvc package for API versioning instead of hand-coded route prefixes; Microsoft.AspNetCore.Mvc.Versioning is the old, deprecated package.

• Apply constraints: Use route constraints such as {id:int} so malformed values fail routing instead of reaching action logic.

• Prefer attribute routing for APIs: It is the default expectation for [ApiController] controllers and makes the contract explicit and versionable.

• Match tooling to the version: Configure Swashbuckle on .NET 8 to document attribute routes, and plan to move to the built-in OpenAPI support when upgrading to .NET 9 or later.

How Route Constraints Work

Constraints are declared inline in a route template using the syntax {parameter:constraint}. During link generation and request matching, routing evaluates the constraint against the route value:

• {id:int} matches only integer segments such as /api/products/42.

• {id:int?} makes the parameter optional; the constraint is checked only when a value is supplied.

• {id:int=1} applies a default when the segment is missing.

• {name:alpha} matches only letters, so /api/products/abc matches but /api/products/abc1 does not.

• Multiple constraints can be chained: {id:int:range(1,999)}.

Built-in Constraints

Where You Use Them

In a controller-based API, constraints go in attribute routes on the controller class or an action method. In Minimal APIs, the same templates are passed to MapGet, MapPost, and related endpoint builders, for example app.MapGet("/products/{id:int}", ...), optionally returning TypedResults such as TypedResults.Ok(product). Constraints are especially useful for disambiguating routes such as /products/{id:int} versus /products/{name:alpha}, and for making routes self-documenting.

Custom Constraints

When no built-in constraint fits, implement IRouteConstraint and register it in the constraint map. The registered name can then be used inline like {id:custom}. Prefer this over a permissive route plus manual parsing, because the endpoint still only matches valid URLs.

Code Example

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Routing;

// Simple model so the example compiles
public record Product(int Id, string Name);

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    // Matches GET /api/products/42, but not /api/products/abc
    [HttpGet("{id:int:min(1)}")]
    public ActionResult<Product> GetById(int id)
    {
        var product = _store.Find(p => p.Id == id);
        return product is null ? NotFound() : Ok(product);
    }

    // Matches GET /api/products/abc (letters only), keeping the two routes distinct
    [HttpGet("{name:alpha:minlength(3)}")]
    public ActionResult<Product> GetByName(string name)
    {
        var product = _store.Find(p => p.Name == name);
        return product is null ? NotFound() : Ok(product);
    }

    private static readonly List<Product> _store = new()
    {
        new Product(1, "Widget"),
        new Product(2, "Gadget"),
    };
}

A custom constraint and its registration:

// Only matches even, positive integers, e.g. /api/orders/8
public sealed class EvenIdConstraint : IRouteConstraint
{
    public bool Match(
        HttpContext? httpContext,
        IRouter? route,
        string routeKey,
        RouteValueDictionary values,
        RouteDirection routeDirection)
    {
        return values.TryGetValue(routeKey, out var value)
            && value is not null
            && int.TryParse(value.ToString(), out var id)
            && id > 0
            && id % 2 == 0;
    }
}

// In Program.cs, before building the app
builder.Services.AddRouting(options =>
{
    options.ConstraintMap.Add("even", typeof(EvenIdConstraint));
});

Best Practices and Pitfalls

• Do not use constraints for validation: a failed constraint removes the route from consideration, which surfaces as a 404, not a 400. Validate input with data annotations or model binding and return ValidationProblem() for bad payloads.

• Keep routes unambiguous: two action templates such as {id:int} and {name} can overlap; constrain both so routing picks one deterministically.

• Prefer specific built-ins over regex: {id:int} is clearer and faster than {id:regex(^\d+$)}.

• Remember optional constraints: with {id:int?}, the constraint is skipped when the segment is absent, so the action must handle a missing or default value.

• Register custom constraints once in AddRouting/Configure<RouteOptions>; the constraint type is applied per match, so keep Match cheap and side-effect free.

What a DTO Is

• Purpose-built container: a DTO has properties only — no business logic, no navigation behaviour, no database attributes.

• Boundary type: it is what the model binder deserializes the request body into and what the serializer writes into the response body.

• Distinct from the domain model: an entity such as Product may have internal state, relationships and persistence concerns; a ProductDto exposes only what the client should see.

Why DTOs Matter

• Contract stability: you can rename or restructure an entity without breaking clients, because the DTO stays the same.

• Security: prevents over-posting. Accepting a CreateProductDto instead of Product stops clients from setting properties such as Id or IsDeleted that you never intended to expose.

• Controlled serialization: avoids lazy-loading or reference-loop problems when returning entity graphs, and lets you shape JSON with System.Text.Json attributes such as [JsonPropertyName].

• Validation in isolation: different DTOs for create, update and read can carry different validation rules — for example [Required] on create but optional on update.

• Aggregation and flattening: a single response can combine data from several entities or services into one payload, which reduces client round trips.

• Versioning: when a response changes, you can add ProductV2Dto alongside the existing DTO instead of forcing a breaking change.

DTOs vs. Entities

Common Patterns

• Per-operation DTOs: ProductCreateDto, ProductUpdateDto, ProductReadDto — each matches one HTTP verb’s needs.

• Manual mapping for small APIs, or a mapper library such as AutoMapper for larger ones; either way, map explicitly so the transformation is visible and testable.

• Return ActionResult<T> from controllers so the DTO type appears in the OpenAPI schema while still allowing status codes such as 201 Created.

Best Practices and Pitfalls

• Do not return entities directly from API actions; it leaks internals and invites over-posting on input models.

• Keep DTOs in the API layer, not in the domain or data project, so the contract stays an API concern.

• Use record types when DTOs are immutable — they give value-based equality with almost no ceremony.

• Validate at the boundary: data annotations plus [ApiController] return a 400 with Problem Details automatically; move cross-field rules to a custom validator when annotations are not enough.

• Map explicitly and test the mapping — silent mis-mapping between similarly named properties is the most common DTO bug.

What It Solves

Without a mapper, every endpoint needs boilerplate like new UserDto { Id = user.Id, Name = user.Name }. AutoMapper copies matching property names and types automatically, so a CreateMap<User, UserDto>() handles all equal-named properties. This keeps controllers focused on HTTP concerns rather than data transformation.

How Integration Works

1. Install the AutoMapper and AutoMapper.Extensions.Microsoft.DependencyInjection NuGet packages.

2. Call AddAutoMapper in Program.cs to scan assemblies for classes inheriting Profile and register IMapper as a singleton.

3. Create profile classes that define CreateMap<Source, Destination>() with optional ForMember customizations for non-conventional cases.

4. Inject IMapper into controllers (or Minimal API handlers) and call Map<T> inside actions.

Code Example

// Program.cs: register AutoMapper (scans the Program assembly for Profile classes)
builder.Services.AddAutoMapper(typeof(Program));

// MappingProfile.cs: group related mappings and customize non-conventional cases
using AutoMapper;

public class MappingProfile : Profile
{
    public MappingProfile()
    {
        CreateMap<User, UserDto>();
        CreateMap<CreateUserDto, User>()
            .ForMember(d => d.CreatedAt, opt => opt.Ignore());
        CreateMap<User, UserSummaryDto>()
            .ForMember(d => d.DisplayName, opt => opt.MapFrom(s => $"{s.FirstName} {s.LastName}"));
    }
}

// UsersController.cs: inject IMapper and map inside actions
[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase
{
    private readonly IMapper _mapper;
    private readonly IUserRepository _repository;

    public UsersController(IMapper mapper, IUserRepository repository)
    {
        _mapper = mapper;
        _repository = repository;
    }

    [HttpGet("{id:int}")]
    public async Task<ActionResult<UserDto>> GetUser(int id)
    {
        var user = await _repository.GetByIdAsync(id);
        if (user is null) return NotFound();
        return Ok(_mapper.Map<UserDto>(user));
    }

    [HttpPost]
    public async Task<ActionResult<UserDto>> CreateUser(CreateUserDto dto)
    {
        var user = _mapper.Map<User>(dto);
        await _repository.AddAsync(user);
        return CreatedAtAction(nameof(GetUser), new { id = user.Id },
            _mapper.Map<UserDto>(user));
    }
}

The same IMapper works in Minimal APIs by injecting it into the handler delegate.

Best Practices and Common Pitfalls

• Prefer ProjectTo<T>() for reads: mapping after loading entities pulls entire rows into memory; projecting the query lets the database return only selected columns.

• Map in one direction per profile: separate Entity -> Dto and Dto -> Entity maps; do not make every map bidirectional.

• Never map across aggregate boundaries in a single call: fetch only what the DTO needs instead of mapping a huge graph.

• Validate before mapping: AutoMapper copies values blindly; rely on [ApiController] model validation and FluentValidation for input rules.

• Keep profiles small and test them: call AssertConfigurationIsValid() or run integration tests to catch unmapped members early, especially after renames.

• Avoid AutoMapper for simple types: mapping a single primitive or a two-property object adds indirection without benefit.

Core Concept

The IHttpActionResult interface defines a single method, ExecuteAsync, which the framework calls to produce an HttpResponseMessage. Controller helper methods like Ok(), NotFound(), and BadRequest() return concrete implementations of this interface. This shifts responsibility from the developer manually constructing messages to the framework handling content negotiation and status codes based on the result type.

Key Advantages

• Testability: Actions returning IHttpActionResult are easier to unit test because you can assert the result type without needing an HTTP host or message handler pipeline.

• Composition: Results can be wrapped or decorated to add cross-cutting concerns, such as logging or custom headers, without changing controller logic.

• Convenience: Built-in helper methods reduce boilerplate code compared to manually instantiating HttpResponseMessage objects.

• Content Negotiation: The framework handles formatter selection automatically based on the object passed to helpers like Ok<T>.

Comparison with HttpResponseMessage

Returning HttpResponseMessage gives complete control over headers and content but couples the action to messaging infrastructure. IHttpActionResult is preferred for most scenarios because it maintains a higher level of abstraction while still allowing access to the response when necessary via ResponseMessage.

Migration to ASP.NET Core

In ASP.NET Core, IHttpActionResult does not exist; it was replaced by IActionResult. Core controllers inherit from ControllerBase and use [ApiController] attributes for automatic model validation and 400 responses. Minimal APIs offer an alternative with endpoint delegates and TypedResults, but controller-based APIs remain the direct successor to Web API 2. Do not attempt to use System.Web.Http types in a Core project, as they belong to different namespaces and runtimes.

Best Practices

• Use specific helper methods (CreatedAtRoute, Conflict) to convey accurate HTTP semantics rather than generic ResponseMessage.

• Avoid returning null; always return a valid result implementation to prevent runtime exceptions.

• For scenarios requiring custom headers, either wrap the result in a custom IHttpActionResult or use ResponseMessage with a manually built HttpResponseMessage.

• Remember that Web API 2 is legacy; new development should target ASP.NET Core where IActionResult and Problem Details are standard.