Chapter 20: Creating an HTTP API using web API controllers

Introduction

This chapter introduces web API controllers as an ASP.NET Core approach for returning client-friendly API responses, building on familiar MVC, routing, binding, and validation concepts.

• Web API controller role: Describe web API controllers as an approach for serving JSON and HTTP status-code responses to client applications such as SPAs or mobile apps, and place them between minimal APIs and server-rendered MVC applications.
  Why it matters: This gives you a framework for understanding why API controllers exist alongside minimal APIs and HTML-rendering controllers.
• Shared framework foundations: Explain that web API controllers reuse ASP.NET Core routing and the MVC design pattern, along with model binding and validation concepts already used by minimal APIs, Razor Pages, and MVC controllers.
  Why it matters: Recognizing the shared foundations means you can reuse knowledge instead of treating API controllers as an entirely separate framework.
• Chapter API controller roadmap: Trace the chapter's planned API-controller topics: creating a project and controller, applying MVC and attribute routing, using the [ApiController] conventions, formatting responses through content negotiation including optional XML support, and choosing between controllers and minimal APIs.
  Why it matters: This roadmap helps you connect each later section to the complete task of designing a controller-based API.

Key terms: web API controllers, minimal APIs, JSON, SPAs, MVC controllers, routing, MVC design pattern, model binding, validation, action methods

20.1 Creating your first web API project

This section creates a web API controller project and shows how controller actions route requests and return data or HTTP results.

• Web API project setup: Describe how to create an ASP.NET Core Web API project and how its Program.cs is configured for API controllers. State that AddControllers() registers controller services without Razor view services, while MapControllers() discovers controller actions as explicitly routed endpoints.
  Why it matters: These registrations make controller action methods available to handle incoming API requests.
• Controller action endpoints: Explain the usual shape of a web API controller: it derives from ControllerBase, commonly has [ApiController], and exposes action methods. Describe how an attribute such as [HttpGet("fruit")] associates an action with both a route template and an HTTP verb.
  Why it matters: Controller actions become the API endpoints through which clients request machine-friendly data.
• Direct model responses: Describe what happens when an action returns a .NET object directly: the object is the API model, is formatted into the response body as JSON by default, and produces a 200 OK response. State that web API controllers can use formats other than JSON when suitable formatters and client capabilities are involved.
  Why it matters: Returning data directly is the straightforward success path for API actions.
• Conditional action results: Explain when an action needs to return IActionResult or ActionResult<T> rather than only data. Describe how ActionResult<T> permits either a successful T value or an ActionResult such as NotFound(), so an invalid fruit id can generate 404 Not Found while a valid id returns the fruit with 200 OK.
  Why it matters: APIs need to express both successful data responses and error status responses from the same endpoint.

Key terms: ASP.NET Core Web API template, dotnet new webapi, AddControllers(), MapControllers(), OpenAPI, Swagger UI, web API controller, ControllerBase, Controller, [ApiController]

20.2 Applying the MVC design pattern to a web API

This section shows that web API controllers follow the same MVC-style request flow as Razor Pages, differing chiefly in how request and response data are represented and formatted.

• Shared request processing flow: Trace how a request to a web API controller moves from routing through model binding, validation, the action method, and the application model before its response returns through the middleware pipeline. Explain that this flow is largely the same as the flow for a Razor Pages request.
  Why it matters: Recognizing the shared flow lets you transfer your Razor Pages and MVC knowledge to API controllers.
• Reusable application model: Explain why page handlers and controller actions should remain simple and delegate business decisions to services in the application model. Describe how this separation allows the same business logic to serve multiple UI paradigms, including Razor Pages and web APIs.
  Why it matters: Keeping UI endpoints thin makes business behavior reusable rather than tying it to a particular kind of client or response.
• API models and output formatters: Describe how an action method creates an API model containing response data, and how an output formatter serializes that model into a machine-readable representation such as JSON or XML. Distinguish this from a PageModel or view model, which also carries metadata used to build an HTML response with a Razor view.
  Why it matters: This explains the principal response-side difference between an API controller and a server-rendered Razor Page.
• Input formatters and binding: State that API controllers use input formatters to accept request data in multiple formats, commonly JSON or XML, before model binding populates a binding model. Explain that apart from accepting such formats, binding and validation work like they do for Razor Pages.
  Why it matters: Input formatters let an API accept machine-readable client data while retaining the familiar binding and validation model.

Key terms: RoutingMiddleware, EndpointMiddleware, model binding, validation, ModelState, ControllerBase, application model, services, business logic, page handlers

20.3 Attribute routing: Linking action methods to URLs

This section introduces attribute routing for web API controllers, showing how route attributes connect action methods to URL templates and reuse standard ASP.NET Core route-template features.

• Attribute routing mechanism: Explain how attribute routing associates a web API controller action method with a URL route template by decorating the action with a [Route] attribute. State that API controllers use the same route-template syntax as minimal APIs and Razor Pages, but specify templates through attributes rather than MapGet/MapPost or the @page directive.
  Why it matters: Attribute routing explicitly determines which controller action handles a requested API URL.
• Independent and multiple action URLs: Describe how one action method can have multiple independently declared [Route] attributes and therefore respond to multiple URLs. Explain that, when RouteAttributes are used, controller and action names do not determine the URL; the attribute template does.
  Why it matters: Understanding that templates, rather than method names, define an API's public URLs helps you design predictable endpoints.
• Route parameter capabilities: Describe that [Route] templates can contain literal segments and route parameters that extract variable URL values, and that parameters can be optional, have default values, or use constraints. Explain why a route constraint should not be used for input validation: a value that fails a constraint does not match the route and produces 404 Not Found rather than the more appropriate 400 Bad Request.
  Why it matters: Separating route matching from input validation gives API clients more meaningful error responses.

Key terms: attribute routing, [Route] attribute, route template, action method, explicit routing, RouteAttribute, controller, route parameter, literal segment, optional parameter

20.3.1 Combining route attributes to keep your route templates DRY

This subsection shows how controller-level and action-level route attributes combine to remove repeated route prefixes while allowing an action to define an absolute route.

• Combined route templates: Explain how a RouteAttribute placed on a controller combines with a RouteAttribute on an action method to form that action's overall route template. Describe how this lets a shared prefix such as "api/car" be declared once on the controller.
  Why it matters: Combining route templates keeps related controller actions consistent and avoids repeating route prefixes.
• DRY route prefixes: Justify placing a common route prefix on a controller instead of repeating it on every action method. Explain that this follows DRY and makes a shared prefix easier and safer to change across multiple actions.
  Why it matters: A single shared prefix prevents inconsistent edits and reduces the chance of route-template typos.
• Absolute action routes: Describe how to make an action method's route template absolute: start its route template with a slash so that it ignores the RouteAttribute on the controller.
  Why it matters: Absolute routes let an individual action opt out of the controller's shared URL prefix when needed.

Key terms: RouteAttribute, controller, action method, route template, DRY, prefix, absolute route template, controller RouteAttribute

20.3.2 Using token replacement to reduce duplication in attribute routing

This section shows how [controller] and [action] token replacement reduces repeated attribute-route text while warning that renames can change public API URLs.

• Attribute route token replacement: Explain how the [controller] and [action] tokens are replaced in attribute routes. State that they become the controller name without its Controller suffix and the action method name, after route attributes have been combined.
  Why it matters: Token replacement lets controllers share route patterns without repeatedly writing controller and action names.
• Public API rename risk: Describe why using [controller] or [action] tokens can make renaming a controller class or action method a breaking public-API change. Explain that static route strings, such as "car", avoid changing the URL when code is renamed.
  Why it matters: A route that follows code names is convenient, but clients can break if a refactoring silently changes its URL.

Key terms: [controller], [action], token replacement, attribute routes, RouteAttributes, public API, static strings

20.3.3 Handling HTTP verbs with attribute routing

This section explains that web API controller routing matches both a URL template and an HTTP verb, using verb-specific attributes to select actions and returning 405 for unsupported methods.

• HTTP verb route matching: Explain that, for web API controllers, the HTTP verb participates in routing together with the route template, so the same URL can route GET and POST requests to different action methods. Distinguish this from Razor Pages, where routing first selects a page by route template and the verb then selects a handler such as OnGet or OnPost.
  Why it matters: Matching on both the URL and method lets an API expose different operations at one resource URL.
• Verb-specific route attributes: Describe using attributes such as [HttpGet], [HttpPost], and [HttpPut] in place of [Route] to restrict an action method to a single HTTP verb. State that analogous attributes exist for the other standard verbs, including DELETE and OPTIONS.
  Why it matters: Verb-specific attributes make each action's allowed operation explicit instead of allowing every method for its route.
• Method-not-allowed responses: State that a request whose URL matches an action's route template but whose HTTP verb does not match the action's required verb receives a 405 Method not allowed response. Use the example that DELETE to the /appointments URL returns 405 when no matching DELETE action is available.
  Why it matters: A 405 response tells an API client that it reached a valid URL with an unsupported request method.

Key terms: HTTP verb, routing, web API controllers, Razor Pages, RoutingMiddleware, action method, [Route], [HttpGet], [HttpPost], [HttpPut]

20.4 Using common conventions with [ApiController]

This section shows how [ApiController] applies web API conventions that remove repetitive controller code and how those conventions can be customized.

• ApiController convention set: Describe how applying the [ApiController] attribute simplifies a web API controller by enforcing attribute routing, automatically returning 400 responses for invalid models, inferring model-binding sources, and converting error status codes to ProblemDetails responses.
  Why it matters: These conventions reduce boilerplate while making API behavior more consistent for callers.
• Manual API-controller boilerplate: Explain the code a controller typically needs without [ApiController]: [FromBody] to bind JSON request data, a ModelState.IsValid check, and a 400 response containing validation details when validation fails. Describe why ProblemDetails or ValidationProblemDetails gives API callers useful error information.
  Why it matters: Knowing the manual alternative makes clear exactly which repetitive responsibilities [ApiController] removes.
• API behavior customization: Describe how to customize [ApiController] conventions by calling ConfigureApiBehaviorOptions() on the IMvcBuilder returned by AddControllers() in Program.cs, including disabling automatic 400 responses when necessary. State that the section recommends retaining the defaults unless there is a real need to change them.
  Why it matters: Customization is available when an API has special requirements, but following the defaults usually preserves productive, consistent behavior.

Key terms: [ApiController], attribute routing, automatic 400 responses, model binding source inference, ProblemDetails, ModelState, [FromBody], ModelState.IsValid, ValidationProblemDetails, 400 Bad Request

20.5 Generating a response from a model

This section introduces how web API controllers format returned models through content negotiation, response headers, and output formatters.

• Content negotiation flow: Explain content negotiation for a web API controller: the client states formats it can accept in the Accept header, the server selects a supported format, serializes the model, and identifies the chosen format in the response Content-Type header.
  Why it matters: Content negotiation lets an API communicate a representation that both the client and server can handle.
• Accept header preferences: Describe how an Accept header can list multiple MIME types with q weightings from 0 to 1, where an omitted weighting is 1.0 and higher weighting expresses a stronger client preference.
  Why it matters: Format preferences allow a client to express several acceptable representations rather than requiring just one.
• JSON fallback and formatters: State that web API controllers use IOutputFormatter implementations to serialize returned models, default to JSON when no requested Accept type can be honored, and serialize JSON properties in camelCase by default; distinguish this formatter support from minimal APIs, which support automatic JSON serialization only.
  Why it matters: Knowing the JSON fallback and formatter boundary explains why a requested format may not be returned and how controller output can be extended.

Key terms: content negotiation, conneg, Accept header, Content-Type header, MIME types, weightings, q value, IOutputFormatter, JSON, XML

20.5.1 Customizing the default formatters: Adding XML support

This section shows how to customize web API formatters by switching JSON libraries and adding XML support so controller responses can honor a client's requested format.

• Default and customizable formatters: Describe the response formats configured by default for ASP.NET Core web APIs and explain that formatters can be customized when an API must produce another format such as XML.
  Why it matters: Formatters determine how the data returned by a controller becomes an HTTP response that clients can consume.
• JSON library selection: Explain that ASP.NET Core uses System.Text.Json by default from .NET Core 3.0 onward, and describe when switching to Newtonsoft.Json can help. State that the Microsoft.AspNetCore.Mvc.NewtonsoftJson package and AddNewtonsoftJson() on the AddControllers() builder make the switch.
  Why it matters: Using Newtonsoft.Json can preserve compatibility with existing applications or JSON from external parties that System.Text.Json will not accept.
• XML formatter configuration: Describe how to add XML formatting by customizing the IMvcBuilder returned from AddControllers() in Program.cs with AddXmlSerializerFormatters(). Explain that this enables XML output and also adds XML input support.
  Why it matters: Adding the formatter lets an API interoperate with clients that request or send XML rather than JSON.
• Content negotiation behavior: Explain content negotiation as the client specifying formats it can handle through the Accept header and the server selecting a format it can produce. Describe that after XML support is added, a text/xml Accept value can cause a controller response to be serialized as XML instead of falling back to JSON.
  Why it matters: Content negotiation enables one API endpoint to serve compatible representations to different kinds of clients.

Key terms: formatters, text/plain, text/html, application/json, XML output formatter, System.Text.Json, Newtonsoft.Json, Json.NET, Microsoft.AspNetCore.Mvc.NewtonsoftJson, AddControllers()

20.5.2 Choosing a response format with content negotiation

This section explains how ASP.NET Core web API controllers choose a response format through content negotiation and the default cases that can alter that choice.

• Content negotiation behavior: Explain that content negotiation lets a client declare acceptable response data types in the Accept header and lets the server choose the best format it can produce.
  Why it matters: It helps you predict why an API returns JSON, XML, plain text, or another representation to different clients.
• Default response-format rules: Describe ASP.NET Core's important defaults: supported output types include application/json, text/plain, and text/html; null models produce 204 No Content; strings without an Accept header produce text/plain; and other models normally use the first applicable formatter, typically JSON.
  Why it matters: These defaults explain responses that can otherwise seem surprising when an API action returns null, a string, or an ordinary model.
• Browser Accept-header exception: Explain that when ASP.NET Core considers a request likely to be from a browser because its Accept header contains */*, it bypasses content negotiation and formats the response as if no Accept header were supplied, typically as JSON for ordinary models.
  Why it matters: This browser-specific rule can make local browser testing appear to ignore a requested format such as XML.
• Configurable negotiation defaults: State that content-negotiation behavior and available formatters are configurable, including making the application respect a browser's Accept header and removing the text/plain formatter for string responses.
  Why it matters: Configuration lets an API's response behavior match its clients instead of relying on defaults that may be unsuitable.

Key terms: content negotiation, Accept header, IOutputFormatters, MIME types, application/json, text/plain, text/html, 204 No Content, StatusCodeResult, */*

20.6 Choosing between web API controllers and minimal APIs

This section provides criteria for choosing minimal APIs or web API controllers for an HTTP API, while emphasizing that the final choice depends on an application's needs and team preferences.

• Technical selection criteria: Distinguish the technical cases that favor web API controllers from those that favor minimal APIs: built-in content negotiation and difficult-to-reuse filters favor controllers, while performance-sensitive applications often favor minimal APIs.
  Why it matters: These trade-offs help you choose an API style based on concrete application requirements rather than fashion.
• New versus existing projects: Explain why the section recommends minimal APIs as the default for a new API project when no compelling controller requirement exists, but recommends retaining web API controllers in an existing controller application for consistency.
  Why it matters: A choice that fits an existing codebase can be better than adopting a newer approach solely because it is newer.
• Conventions and endpoint organization: Describe the preference trade-off between controllers' convention-over-configuration action-method structure and minimal APIs' explicit endpoint mapping and flexible organization.
  Why it matters: The amount of framework convention versus explicit setup affects how your team structures and understands an API.
• Experience-based choice: Explain how prior web API controller experience can reasonably influence a short-term productivity decision, while recognizing that the section considers it a weaker reason because minimal APIs are conceptually simpler.
  Why it matters: Recognizing the learning-cost trade-off lets a team make a deliberate practical choice without mistaking familiarity for a universal technical requirement.

Key terms: content negotiation, conneg, minimal APIs, web API controllers, filter pipeline, MVC framework, consistency, convention over configuration, action methods, controller class

20.7 Summary

This summary recaps how web API controllers route requests, apply API conventions, format responses, and compare with minimal APIs.