Skip to main content

Notification API Overview

Summary​

The native Notification API is a .NET 8 Minimal API composed in Program.cs and mapped by a single extension method, MapNotificationEndpoints, which delegates to three private mapping methods. Two further endpoints — service information and health — are contributed outside that extension.

Audience​

API consumers, engineers, architects, QA, support, security reviewers and implementation partners.

Minimal API organization​

NotificationEndpoints.MapNotificationEndpoints calls, in order, MapInboxEndpoints, MapTemplateEndpoints and MapAdminAndTestEndpoints. There are no controllers in the extracted service; every native operation is a Minimal API lambda registered with MapGet, MapPost or MapPut.

Every native handler carries a WithName(...) endpoint name. No native handler declares RequireAuthorization, an authorization policy, a rate limiter, an output cache or an API version.

Route groups​

GroupMapGroup prefixWithTags valueMapped operations
Inbox/notificationsnotifications2
Templates/notification-templatesnotification-templates4
Administration and test hooks/notificationsnotifications-admin9

Two groups share the /notifications prefix and are distinguished only by their Swagger tag, not by path.

API architecture​

Shared operational endpoints​

Program.cs maps GET /health through MapHealthChecks and GET / through the shared-kernel MapHrSuitServiceInfo extension. These are the only two native endpoints not defined in NotificationEndpoints.cs, and the only two that return the shared ApiResponse<T> or health-report shapes rather than service-local projections.

Gateway participation​

The gateway defines a toggled route for the /api/notifications prefix and a permanently registered shadow route for /notifications. See gateway and compatibility for the verified route configuration and its path-alignment caveat.

Current maturity​

Transitional. The native surface is complete for the operations it maps, but coexists with an authorized monolith surface that carries a different contract, and no versioning or in-service authorization is registered.

Classification​

Implemented native organization; gateway participation is Transitional.

Requires confirmation​

Whether the two /notifications groups are intended to remain merged under one path, and whether the native surface is intended for direct external consumption, require confirmation.

See Also​

Keywords​

  • Notification API
  • API Overview
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/notification-service/Program.cs
  • microservices/src/shared-kernel/Extensions/EndpointRouteBuilderExtensions.cs
  • microservices/src/gateway-api/Program.cs

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-21
  • Review cycle: Quarterly