A route returns plain text for validation errors and ProblemDetails for auth errors. What should you fix first?

Standardize failure responses so clients can handle errors reliably.

Hide authorization policies in the repository.

Make validation depend on generated SQL.

A teammate wants to hide endpoint filter inside a convenient helper. What should you check first?

Whether the helper makes ownership, inputs, failures, and tests easier to review.

Whether it reduces the number of files regardless of behavior.

Whether it removes the need for the lesson checklist.

Whether it can skip the production signals for this course.

Which artifact best proves this .NET APIs lesson is ready for review?

A repeatable check tied to authorization policy and OpenAPI response review.

A note that says the happy path was manually clicked once.

A screenshot with no command, test, or failure-mode context.

A broad refactor that avoids the specific lesson outcome.

Intermediate API design: a teammate says the happy path works, but "ProblemDetails as a client contract" is still implicit. What should you ask for before merging?

A small contract, test, or review artifact that proves problemdetails as a client contract under a realistic failure case.

Skip compiler, OpenAPI, SQL, or host evidence until the capstone.

Hide the decision inside framework defaults so reviewers have less to read.

Treat production behavior as separate from the lesson implementation.

A reviewer has five minutes to evaluate this intermediate .NET APIs slice. Which evidence is strongest?

A focused artifact for endpoint filters with contract tests plus a repeatable test, log, OpenAPI diff, or deployment check.

A passing build with no note about contracts, query shape, or operations.

A screenshot of Swagger without checking response or failure cases.

A broad rewrite that does not map to the stage milestone.

Learn / .NET API Engineering Path

Validation, Auth, and Problem Details

Design endpoint filters, authorization policies, and problem responses as one consistent contract instead of scattered checks.

Course: .NET API Engineering Path. Level: Advanced. Topic: Typed backend.

Stage: intermediate - Intermediate API design - Validation, authorization, and error contracts. Turn cross-cutting checks into predictable endpoint behavior that clients and reviewers can trust.

Outcomes

Return stable ProblemDetails for validation and auth failures.
Keep authorization policy names explicit.
Test one denied and one invalid request.

Concepts

endpoint filter
authorization policy
ProblemDetails
contract test

Concept flow

Show how validation, authorization, and error contracts moves from trigger to implementation outcome in .NET APIs.

Client
Auth policy
Validation filter
Endpoint
ProblemDetails
OpenAPI

Session flow

Model endpoint filter (concept, 10 min) — Name the decisions behind endpoint filter before writing code.
- Return stable ProblemDetails for validation and auth failures.
- Explain where endpoint filter belongs in order management API.
Build the vertical slice (walkthrough, 18 min) — Implement the smallest useful slice in Orders/OrderValidationFilter.cs.
- Keep authorization policy names explicit.
- Connect authorization policy to a working example.
Verify and harden (exercise, 12 min) — Assert the ProblemDetails shape in an HTTP test.
- Test one denied and one invalid request.
- Record one risk or follow-up before moving on.

Code example

C# in Orders/OrderValidationFilter.cs.

public sealed class OrderValidationFilter : IEndpointFilter
      {
          public async ValueTask<object?> InvokeAsync(EndpointFilterInvocationContext context, EndpointFilterDelegate next)
          {
              var request = context.GetArgument<CreateOrderRequest>(0);
              if (request.TotalCents <= 0)
              {
                  return TypedResults.ValidationProblem(new Dictionary<string, string[]>
                  {
                      ["totalCents"] = ["Total must be positive."]
                  });
              }
      
              return await next(context);
          }
      }

Walkthrough examples

Validation, Auth, and Problem Details in a order management API — A team is extending a production-grade ASP.NET Core order API and needs this lesson's pattern to be clear enough for review, testing, and future maintenance.
- File: Orders/OrderValidationFilter.cs
- File: src/Orders.Application/validation-auth-and-problem-details.cs
- File: tests/Orders.Api.Tests/validation-auth-and-problem-details.Tests.cs
- File: docs/dotnet-advanced/validation-auth-and-problem-details.md
- Start from the provided C# snippet and make the intent visible in names and boundaries.
- Apply the checklist item "Validation response is predictable" before adding extra behavior.
- Write down how the implementation changes when authorization policy fails or becomes slow.

Practice

Add one endpoint filter for request validation.
Name the authorization policy used by the route.
Assert the ProblemDetails shape in an HTTP test.

Checklist

Validation response is predictable
Auth policy is visible on the route
OpenAPI documents failure responses
Tests cover denied and invalid requests

Quiz prompts

A route returns plain text for validation errors and ProblemDetails for auth errors. What should you fix first? — Intermediate API design includes consistent client-facing failure contracts, not only happy-path responses.
A teammate wants to hide endpoint filter inside a convenient helper. What should you check first? — Place endpoint filter at the boundary that keeps order management API behavior explicit, testable, and reviewable.
Which artifact best proves this .NET APIs lesson is ready for review? — Production-ready learning needs evidence: a test, trace, command, screenshot, or log that catches the risk again.
Intermediate API design: a teammate says the happy path works, but "ProblemDetails as a client contract" is still implicit. What should you ask for before merging? — ProblemDetails as a client contract belongs in the intermediate stage only when the decision is visible, testable, and tied to a realistic failure mode.
A reviewer has five minutes to evaluate this intermediate .NET APIs slice. Which evidence is strongest? — Add validation, authorization, and ProblemDetails to the order API, then prove the contract with denied, invalid, and conflict HTTP tests.

Flashcards

Intermediate API design: what decision does "ProblemDetails as a client contract" force you to make? Return stable error shapes for validation, denied access, not-found, and conflict cases. Evidence prompt: Create an error contract matrix and assert one ProblemDetails response in an HTTP test.
Intermediate API design: what decision does "Authorization policies and ownership checks" force you to make? Make authorization requirements visible at the route boundary and keep ownership checks close to the use case. Evidence prompt: Add one named policy and test both a denied request and an allowed owner request.
Intermediate API design: what decision does "Endpoint filters with contract tests" force you to make? Use filters for repeated validation while preserving route-level evidence for generated contracts. Evidence prompt: Add a validation filter and capture the OpenAPI response section that proves the failure path.
In .NET APIs, what should you remember about endpoint filter? endpoint filter matters here because it supports "Return stable ProblemDetails for validation and auth failures.".
In .NET APIs, what should you remember about authorization policy? authorization policy matters here because it supports "Keep authorization policy names explicit.".
In .NET APIs, what should you remember about ProblemDetails? ProblemDetails matters here because it supports "Test one denied and one invalid request.".
In .NET APIs, what should you remember about contract test? contract test matters here because it supports "Return stable ProblemDetails for validation and auth failures.".

Labs

Ship a validation, auth, and problem details slice — Extend a production-grade ASP.NET Core order API with a small but reviewable feature that proves the lesson's architecture in code.
- Add validation, authorization, and ProblemDetails to the order API, then prove the contract with denied, invalid, and conflict HTTP tests.
- Create an error contract matrix and assert one ProblemDetails response in an HTTP test.
- Add one named policy and test both a denied request and an allowed owner request.
- Add a validation filter and capture the OpenAPI response section that proves the failure path.
- Add one endpoint filter for request validation.
- Name the authorization policy used by the route.
- The lab demonstrates the intermediate api design outcome without skipping earlier contract evidence.
- Each subtopic has a concrete artifact: ProblemDetails as a client contract, Authorization policies and ownership checks, Endpoint filters with contract tests.
- The review notes explain how this level changes ownership, verification, or operational risk.

Challenge

Review-ready validation, auth, and problem details (Stretch) — Add validation, authorization, and ProblemDetails to the order API, then prove the contract with denied, invalid, and conflict HTTP tests.
- All checklist items are either implemented or documented with a reason.
- The change can be understood from Orders/OrderValidationFilter.cs plus one short note.
- The concept diagram names ownership, failure handling, and verification points.
- A teammate could run the verification steps without asking for hidden context.

Canonical lesson URL