ASP.NET Core Web API & REST
What it is & where it is used
ASP.NET Core Web API builds HTTP services that return data (usually JSON) for SPAs (React/Angular/Vue), mobile apps and other services. Two programming models:
- Controller-based APIs —
[ApiController]classes with actions (feature-rich: filters, model binding conventions). - Minimal APIs (.NET 6+) — lambda endpoints mapped in
Program.cs(app.MapGet(...)), less ceremony, AOT-friendly.
Related technologies: gRPC (high-performance HTTP/2 + Protobuf RPC), SignalR (real-time WebSockets), GraphQL (Hot Chocolate), YARP (reverse proxy/API gateway).
REST (Representational State Transfer, Roy Fielding, 2000) constraints: client–server, stateless, cacheable, uniform interface (resources identified by URIs, manipulated via representations, standard HTTP methods), layered system, (optional) code on demand.
Versions & history
| Version | Highlights for APIs |
|---|---|
| ASP.NET Web API 1/2 (2012/2013) | On .NET Framework; attribute routing in v2; OWIN |
| ASP.NET Core 1.0 (2016) | Web API merged into MVC: one Controller base |
| 2.1 (2018) | [ApiController] (automatic 400s, binding inference), ControllerBase, ActionResult<T>, ProblemDetails |
| 3.0 (2019) | Endpoint routing, System.Text.Json default, gRPC templates |
| 6 (2021) | Minimal APIs, WebApplication minimal hosting |
| 7 (2022) | Route groups, endpoint filters, typed results, rate limiting, output caching |
| 8 (2023) | Native AOT for Minimal APIs, [FromForm] in Minimal APIs, keyed services, Identity API endpoints, IExceptionHandler |
| 9 (2024) | Built-in OpenAPI document generation (Microsoft.AspNetCore.OpenApi, Swashbuckle removed from templates), HybridCache |
| 10 (2025) | OpenAPI 3.1, built-in validation for Minimal APIs (AddValidation()), Server-Sent Events results, JSON Patch with System.Text.Json |
Lifecycle
API request lifecycle:
- Client sends an HTTP request (method + URL + headers + body).
- Kestrel → middleware: exception handler → HTTPS → CORS → authentication (JWT validated) → authorization → rate limiter → response caching/output caching.
- Endpoint routing selects the action/minimal endpoint.
- Controller APIs: filters → model binding (
[FromBody]JSON deserialised with System.Text.Json) → validation ([ApiController]returns 400 ProblemDetails automatically if invalid) → action. - Action calls services/repositories (async I/O to DB/HTTP).
- Result (
Ok(dto),CreatedAtAction,NotFound()) → content negotiation picks a formatter (JSON by default) → serialised response with status code and headers. - Logging/telemetry middleware records the request; response returns.
API lifecycle (product): design (OpenAPI contract) → implement → test (unit, integration, contract) → document → version → deploy behind a gateway → monitor → deprecate old versions (Sunset header) → retire.
Tools used to develop
| Tool | Use |
|---|---|
| Postman, Insomnia, Bruno | Manual and collection-based API testing |
.http files in Visual Studio / VS Code REST Client | Requests stored with the code |
| Swagger UI / Scalar / ReDoc | Interactive docs from the OpenAPI document |
| NSwag, Kiota, OpenAPI Generator | Generate typed clients |
| Microsoft.AspNetCore.Mvc.Testing | Integration tests (WebApplicationFactory) |
| k6, JMeter, NBomber, Azure Load Testing | Load testing |
| Azure API Management, YARP, Ocelot | Gateways |
| Application Insights, OpenTelemetry, Seq, Serilog | Observability |
| curl / httpie | Command-line testing |