ASP.NET Core APIs and Endpoint Design

HTTP methods carry semantics: GET is safe, PUT is idempotent replacement, PATCH is partial change, POST creates or invokes non-idempotent processing, and DELETE removes. Status codes and headers form part of the contract, not decoration.

Advanced C# work improves when you separate language syntax, runtime behavior, and application policy. Write down which layer owns the guarantee in this lesson. Then identify the observable evidence—a compiler rejection, test result, generated query, trace, or measurement—that would prove the model correct.

Bind request DTOs, validate them, invoke an application service, and return typed results. Created responses include a Location header. Problem Details provides a consistent error shape. Endpoint groups can apply common prefixes, tags, authorization, and filters.

The starter isolates one part of the mental model so it can run in the browser. The exercise moves the same rule into a current local .NET project where packages, framework hosting, diagnostics, and multi-file tests are available.

using System;

class ApiResult
{
  public int StatusCode { get; private set; }
  public string Body { get; private set; }
  public ApiResult(int statusCode, string body) { StatusCode = statusCode; Body = body; }
}
class Program
{
  static ApiResult Find(bool exists) { return exists ? new ApiResult(200, "found") : new ApiResult(404, "missing"); }
  static void Main() { Console.WriteLine(Find(false).StatusCode); }
}

404

Returning 200 for every outcome forces clients to parse prose. Exposing EF entities couples storage shape to the public API. Blocking calls waste request threads, and ignoring RequestAborted continues work a disconnected client no longer needs.

Classify each failure as a contract violation, transient operational failure, permanent dependency response, concurrency conflict, or programmer defect. That classification determines whether to reject, retry, compensate, cancel, or fail fast. A generic catch-and-continue policy destroys the information needed to make that decision.

Generate and review OpenAPI, version incompatible changes deliberately, impose body and pagination limits, and write contract examples. Measure endpoint latency and dependency time separately.

Finish by making the result operable. Add structured diagnostics at the boundary, propagate cancellation, avoid sensitive data, and record SDK and dependency versions. Test the public behavior instead of private implementation details. If a framework or provider performs translation, serialization, concurrency, or I/O, include at least one test against the real production technology.

A senior-level review should be able to answer four questions: what contract is promised, who owns lifetime and cleanup, how failures become visible, and what evidence supports the design. If any answer depends on “the framework probably handles it,” inspect the documentation or runtime behavior and turn the assumption into a checked decision.