refactor: migrate Exceptionless.Web to Minimal APIs with Foundatio.Mediator by niemyjski · Pull Request #2257 · exceptionless/Exceptionless

niemyjski · 2026-05-27T03:45:52Z

Summary

Migrate all Exceptionless.Web controllers to Minimal API endpoints using Foundatio.Mediator for command/query dispatch.

What Changed

Architecture: Controllers → thin endpoint functions that delegate to Mediator handlers
Entry Point: Consolidated Startup.cs into single minimal hosting Program.cs
Job Runner: Modernized to WebApplication.CreateBuilder() minimal hosting
OpenAPI: Preserved all documentation, tags, parameters, response codes via EndpointDocumentationOperationTransformer
Testing: Route manifest + OpenAPI snapshot tests ensure no regressions

Key Invariants Preserved

Invariant	Status
All 184 routes	✅ Verified via endpoint manifest
All 137 documented OpenAPI operations	✅
128/128 summaries	✅
355 parameter descriptions	✅
358 response descriptions	✅
All tags match old controller-derived names	✅
Security schemes	✅
Route constraints (token, tokens, objectid)	✅
Auth policies on every endpoint	✅
ProblemDetails shape (instance, reference-id, errors, lower_underscore keys)	✅
Delta<T> patch behavior	✅
X-Exceptionless-Client header priority	✅
ThrottlingMiddleware / OverageMiddleware	✅ Unchanged
Health checks (/health, /ready)	✅

Structure

src/Exceptionless.Web/Api/
  Endpoints/     — 13 endpoint files (thin HTTP adapters)
  Messages/      — Command/query records
  Handlers/      — Use-case logic (ported from controller actions)
  Filters/       — AutoValidationEndpointFilter, ConfigurationResponseEndpointFilter
  Results/       — ApiResults, OkWithResourceLinks, CollectionResult
  Infrastructure/ — Pagination, TimeRangeParser, CurrentUserAccessor
  OpenApi/       — Build-time generation config

Migration Order (per OpenSpec)

Contract/OpenAPI baseline tests → 2. Infrastructure → 3. Mediator registration → 4. Status/Utility → 5–17. Feature slices → 18. Remove controllers → 19. Final audit

Breaking Changes

None. All public routes, auth behavior, and response shapes are preserved.

Known Acceptable Differences

StringStringValuesKeyValuePair schema removed (MVC model binding artifact) → ProblemDetails schema added (from .ProducesProblem())
Versioned subscribe route /api/v{apiVersion:int}/webhooks/subscribe lacks =2 default (Minimal API limitation, canonical /api/v2/webhooks/subscribe route exists)

Planning artifacts for migrating Exceptionless.Web controllers to Minimal APIs with Foundatio.Mediator dispatch, preserving all existing API behavior. Change deliverables: - proposal.md: justification, classification, rollback plan - design.md: architecture, endpoint/mediator/handler patterns - tasks.md: 19 ordered migration tasks with verification steps - acceptance.md: SHALL/SHALL NOT acceptance criteria - risks.md: 9 risks with mitigation strategies New specs (testable SHALL statements): - api-architecture: endpoint registration, mediator dispatch, DI - api-contract: route/response/header preservation - api-validation: DataAnnotation + MiniValidation - api-problem-details: error response shape - api-middleware: throttling, overage, filters, pipeline ordering - api-openapi: runtime/build-time generation, snapshot tests - api-patching: Delta<T> preservation, no JSON Patch Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Merge all service registrations and middleware pipeline into single Program.cs - Use WebApplication.CreateBuilder() minimal hosting pattern - Add Foundatio.Mediator 1.2.1 package reference - Add Microsoft.Extensions.ApiDescription.Server for build-time OpenAPI - Add stub MapApiEndpoints() extension for future endpoint registrations - Update AppWebHostFactory to use WebApplicationFactory<Program> - Remove Startup.cs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- ApiEndpointGroups: shared route group builder with auth policy - ApiResults: OkWithLinks, OkWithResourceLinks, Permission, WorkInProgress helpers - Pagination: limit/page/skip helpers extracted from base controller - TimeRangeParser: time range parsing extracted from base controller - CurrentUserAccessor: HttpContext user helpers - ConfigurationResponseEndpointFilter: config version header filter - ApiResponseHeadersEndpointFilter: common response headers - ApiValidation: MiniValidation wrapper for endpoint validation Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Create Messages/StatusMessages.cs with command/query records - Create Handlers/StatusHandler.cs and UtilityHandler.cs with mediator handlers - Create Endpoints/StatusEndpoints.cs and UtilityEndpoints.cs - Remove StatusController.cs and UtilityController.cs - Wire up MapApiEndpoints() in ApiEndpoints.cs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- TokenEndpoints: full CRUD with org/project scoped routes - WebHookEndpoints: CRUD plus Zapier subscribe/unsubscribe/test - StripeEndpoints: webhook receiver with signature validation - All use Foundatio.Mediator handler pattern - Remove TokenController, WebHookController, StripeController Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ts with Foundatio.Mediator Replace MVC controllers with the same Minimal API + Mediator pattern used by Token, WebHook, and Status endpoints. Each controller is split into Messages (records), Handler (business logic), and Endpoints (HTTP routing via IMediator). Preserves all routes, route constraints (:objectid, :token, :minlength), auth policies (User, GlobalAdmin), named routes (GetSavedViewById, GetUserById), and behavior including predefined saved view management, email verification, admin role management, and rate-limited email updates. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- ProjectEndpoints: full CRUD, config, notifications, integrations, Slack - OrganizationEndpoints: full CRUD, invoices, plans, suspend - Preserve all routes, auth policies, route names - Remove ProjectController.cs and OrganizationController.cs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- AuthEndpoints: login, signup, OAuth, forgot-password, change-password - Preserve AllowAnonymous on public auth routes - Port complete OAuth flow (Google, Facebook, GitHub, Microsoft) - Remove AuthController.cs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace MVC controllers with Foundatio.Mediator-based Minimal API endpoints following the established pattern (Messages/Handlers/Endpoints). All routes, authorization policies, and route names are preserved. - AdminController → AdminMessages + AdminHandler + AdminEndpoints - StackController → StackMessages + StackHandler + StackEndpoints - EventController → EventMessages + EventHandler + EventEndpoints - Update ApiEndpoints.cs to register new endpoint groups - Fix ControllerManifestTests assembly reference (no controllers remain)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Remove AddControllers() and MapControllers() from Program.cs - Remove AddAutoValidation() (MVC-specific filter) - Remove ExceptionlessApiController, ReadOnlyRepositoryApiController, RepositoryApiController base classes - Keep shared types (PermissionResult, TimeInfo, WorkInProgressResult, ModelActionResults) - Update ControllerManifestTests to verify no MVC controllers remain - Full solution builds with 0 errors Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- EndpointManifestTests: verifies all endpoint classes are registered - OpenApiSnapshotTests: lightweight test app for OpenAPI document verification - MinimalApiTestApp: shared test host without Elasticsearch dependency - SnapshotTestHelper: shared snapshot comparison utility - Remove old OpenApiControllerTests (replaced by snapshot approach) - Generate initial endpoint-manifest.json and openapi.json baselines Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ebhook subscribe route, user-agent - Restore :token/:tokens route constraints on token endpoints - Add canonical api/v2/webhooks/subscribe route (was only versioned) - Create AutoValidationEndpointFilter for Minimal API auto-validation - Register auto-validation filter on all endpoint groups - Remove dead ApiEndpointGroups.cs - Fix UserAgent header regression: prefer X-Exceptionless-Client over User-Agent - Fix Stripe trailing slash: map POST directly without empty-string sub-route - Delete obsolete controller-manifest.json test fixture Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Routes now match pre-migration manifest (184 endpoints, all constraints preserved). Only remaining diff: versioned subscribe route template lacks =2 default (Minimal API limitation; covered by canonical api/v2/webhooks/subscribe route). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Replace Host.CreateDefaultBuilder()/ConfigureWebHostDefaults() with WebApplication.CreateBuilder() for consistency with the web project. Preserves all behavior: health checks, Serilog, APM, job registration. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Port all XML doc summaries, parameter descriptions, and response descriptions from the old MVC controllers to Minimal API endpoints using .WithSummary() and .WithMetadata(EndpointDocumentation) with a custom IOpenApiOperationTransformer. Results vs old spec (128/348/244 target): - Summaries: 128/128 (100%) - Parameter descriptions: 298/348 (86% - gap is from params not in lambda signatures like headers and manual query params) - Response descriptions: 266 total responses documented (exceeds 244) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Extend EndpointDocumentationOperationTransformer to support injecting additional parameters (e.g. User-Agent header, query string arrays). Add Produces<T>() and ProducesProblem() declarations across all endpoint files to document response types and error codes. This brings coverage to: - Summaries: 128 (unchanged) - Parameters: 409 (was 287, added 122) - Response codes: 353 (was 231, added 122) - Schemas: 49 (was 43, added 6) Update snapshot test assertion from 200 to 202 for user-description endpoint to match its actual Accepted semantics.

Change endpoint group tags from plural to singular to match the old MVC controller-derived tags (Event, Organization, Project, Stack, User, etc.). Add explicit WithTags to Token, WebHook groups and all v1 endpoints that previously inherited tags from their controller class. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

- Disable ValidateOnBuild in WebApplication.CreateBuilder since the service graph uses lambda factories (queues, caching, Elasticsearch) that resolve dependencies at runtime via IServiceProvider. The old Generic Host path did not enable this validation. - Add using/dispose to StreamReader in StripeEndpoints - Add using/dispose to MemoryStream in EventHandler - Add using/dispose to ScopedCacheClient in EventHandler and StackHandler - Refactor AutoValidationEndpointFilter to use Where() filtering - Refactor DeleteEvents/DeleteStacks to use LINQ Where() instead of mutating a list inside a foreach loop Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

The ValidateOnBuild=false in Program.cs via builder.Host.UseDefaultServiceProvider() does not take effect in the minimal hosting model when used with WebApplicationFactory. The ConfigureHostBuilder stores but may not replay service provider options. Fix: Add builder.UseDefaultServiceProvider() in AppWebHostFactory.ConfigureWebHost where the IWebHostBuilder properly replaces the service provider factory. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Copilot wasn't able to review any files in this pull request.

Copilot

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.

…-mediator-openapi-migration # Conflicts: # .agents/skills/backend-architecture/SKILL.md # src/Exceptionless.Web/Api/Handlers/SavedViewHandler.cs # src/Exceptionless.Web/ClientApp/src/lib/features/organizations/api.svelte.ts # src/Exceptionless.Web/ClientApp/src/lib/features/users/api.svelte.ts # src/Exceptionless.Web/Controllers/EventController.cs # src/Exceptionless.Web/Controllers/OrganizationController.cs # src/Exceptionless.Web/Controllers/ProjectController.cs # src/Exceptionless.Web/Controllers/StatusController.cs # src/Exceptionless.Web/Controllers/UserController.cs # tests/Exceptionless.Tests/Controllers/Data/controller-manifest.json # tests/Exceptionless.Tests/Controllers/Data/openapi.json

…al-api-mediator-openapi-migration # Conflicts: # src/Exceptionless.Web/Api/Handlers/SavedViewHandler.cs # src/Exceptionless.Web/Controllers/AdminController.cs # src/Exceptionless.Web/Controllers/EventController.cs # src/Exceptionless.Web/Controllers/OrganizationController.cs # src/Exceptionless.Web/Controllers/ProjectController.cs # src/Exceptionless.Web/Controllers/StackController.cs # src/Exceptionless.Web/Controllers/StatusController.cs # src/Exceptionless.Web/Startup.cs # src/Exceptionless.Web/Utility/Delta/Delta.cs # src/Exceptionless.Web/Utility/Delta/DeltaJsonConverter.cs # tests/Exceptionless.Tests/AppWebHostFactory.cs # tests/Exceptionless.Tests/Controllers/Data/openapi.json # tests/Exceptionless.Tests/Controllers/EventControllerTests.cs # tests/Exceptionless.Tests/Controllers/OpenApiSnapshotTests.cs # tests/Exceptionless.Tests/Serializer/SnakeCaseLowerNamingPolicyTests.cs

# Conflicts: # src/Exceptionless.Web/Controllers/Base/ExceptionlessApiController.cs # src/Exceptionless.Web/Controllers/EventController.cs # tests/Exceptionless.Tests/Controllers/Data/openapi.json

# Conflicts: # src/Exceptionless.Web/Controllers/AdminController.cs

ejsmith · 2026-06-25T02:33:05Z

Fixed the partial-update compatibility issue in 113c44b.

What changed:

Update endpoints now accept both RFC 6902 JSON Patch arrays and legacy object-shaped partial bodies before dispatching the same mediator update messages.
Kept OpenAPI request-body metadata as JSON Patch and restored explicit endpoint display names so endpoint/OpenAPI snapshots stay stable.
Reused the same shared parser for projects, tokens, users, organizations, and saved views.

Verification:

dotnet build tests\Exceptionless.Tests\Exceptionless.Tests.csproj --configuration Release --no-restore --verbosity minimal /m:1
dotnet test tests\Exceptionless.Tests\Exceptionless.Tests.csproj --configuration Release --no-build -- --filter-class Exceptionless.Tests.Controllers.TokenControllerTests --filter-class Exceptionless.Tests.Controllers.UserControllerTests --filter-class Exceptionless.Tests.Controllers.OrganizationControllerTests --filter-class Exceptionless.Tests.Controllers.SavedViewControllerTests
dotnet test tests\Exceptionless.Tests\Exceptionless.Tests.csproj --configuration Release --no-build -- --filter-class Exceptionless.Tests.Controllers.OpenApiSnapshotTests --filter-class Exceptionless.Tests.Controllers.EndpointManifestTests --filter-class Exceptionless.Tests.Controllers.ControllerManifestTests

Note: the snapshot run on Windows required temporary local LF normalization of AuthEndpoints.cs because raw string descriptions emit CRLF from a CRLF checkout; that file was restored and is not part of the commit.

github-actions · 2026-06-25T05:06:37Z

Package	Line Rate	Branch Rate	Complexity	Health
Exceptionless.AppHost	39%	40%	134	❌
Exceptionless.Core	70%	62%	8002	➖
Exceptionless.Insulation	23%	23%	203	❌
Exceptionless.Web	77%	60%	5411	✔
Summary	72% (17585 / 24558)	61% (7910 / 12978)	13750	➖

niemyjski and others added 18 commits May 26, 2026 17:15

Fix minimal API parity regressions

31643d3

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

niemyjski requested a review from Copilot May 27, 2026 03:46

niemyjski self-assigned this May 27, 2026

Copilot AI reviewed May 27, 2026

github-code-quality Bot found potential problems May 27, 2026

View reviewed changes

niemyjski force-pushed the niemyjski/minimal-api-mediator-openapi-migration branch from ecc217a to 30aed31 Compare May 27, 2026 04:26

github-code-quality Bot found potential problems May 27, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Program.cs Fixed

Comment thread src/Exceptionless.Web/Program.cs Fixed

niemyjski requested a review from Copilot May 27, 2026 12:42

Copilot AI reviewed May 27, 2026

View reviewed changes

niemyjski requested a review from Copilot May 27, 2026 13:34

niemyjski requested a review from Copilot May 31, 2026 23:20

Copilot AI reviewed May 31, 2026

github-code-quality Bot found potential problems Jun 14, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs Fixed

Comment thread src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs Fixed

Use mediator result mapper for minimal API responses

37a2285

github-code-quality Bot found potential problems Jun 14, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Api/Handlers/EventHandler.cs Fixed

Remove legacy direct result mapping overloads

28d138a

github-code-quality Bot found potential problems Jun 14, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs Fixed

Pilot mediator generated endpoints for status routes

3bf24dd

github-code-quality Bot found potential problems Jun 14, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Api/Handlers/EventHandler.cs Fixed

ejsmith added 2 commits June 14, 2026 23:14

Convert simple admin routes to mediator endpoints

67da4d0

Chain mediator result mapping from AddMediator

691c46f

github-code-quality Bot found potential problems Jun 15, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Api/Handlers/AdminHandler.cs Fixed

Comment thread src/Exceptionless.Web/Api/Handlers/OrganizationHandler.cs Fixed

Use mediator 1.3.1 endpoint groups

89a1b4d

github-code-quality Bot found potential problems Jun 15, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Api/Handlers/AdminHandler.cs Fixed

niemyjski added 2 commits June 18, 2026 07:11

fix: address PR review feedback

fd25bdf

github-code-quality Bot found potential problems Jun 18, 2026

View reviewed changes

ejsmith added 7 commits June 22, 2026 09:31

Merge remote-tracking branch 'origin/main' into pr-2257

8f5dde3

# Conflicts: # src/Exceptionless.Web/Controllers/Base/ExceptionlessApiController.cs # src/Exceptionless.Web/Controllers/EventController.cs # tests/Exceptionless.Tests/Controllers/Data/openapi.json

Fix event include total merge fallout

57f0363

Relax Elasticsearch test startup wait

d16aa20

Merge remote-tracking branch 'origin/main' into pr-2257

be5f960

Merge remote-tracking branch 'origin/main' into pr-2257

159c257

# Conflicts: # src/Exceptionless.Web/Controllers/AdminController.cs

Fix cursor pagination next links

9b16fa9

Preserve legacy partial update bodies

113c44b

Address code quality review feedback

8d4f2f5

github-code-quality Bot found potential problems Jun 25, 2026

View reviewed changes

Comment thread src/Exceptionless.Web/Api/Handlers/WebHookHandler.cs Fixed

Refine webhook access filtering

531b506

Uh oh!

Uh oh!

Conversation

niemyjski commented May 27, 2026

Summary

What Changed

Key Invariants Preserved

Structure

Migration Order (per OpenSpec)

Breaking Changes

Known Acceptable Differences

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ejsmith commented Jun 25, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants