Skip to main content

Notification API Request Lifecycle

Summary​

The pipeline is short. Correlation middleware runs first, Swagger middleware follows, then the request reaches a Minimal API handler directly. There is no authentication, authorization, exception-handling, CORS, rate-limiting or response-caching middleware in the reviewed composition.

Audience​

Engineers, architects, QA, support and security reviewers.

Middleware order​

The order established in Program.cs is exactly:

  1. Correlation identifier middleware.
  2. Swagger document middleware.
  3. Swagger UI middleware.
  4. Endpoint execution — health, service information, then the three notification groups.

Correlation behavior (verified): the middleware resolves a correlation identifier from the request header, generating one when absent, then writes it onto the request headers, into the request items collection and onto the response headers. It opens a logging scope carrying the correlation identifier and the resolved service name for the duration of the request, so every log entry written during the request inherits both.

Standard request sequence​

Parameter binding​

Native handlers bind directly in the lambda signature. Route values bind by name with a GUID constraint where applicable; query values bind by name, with nullable types making them optional; request bodies bind as the four declared request classes; and framework services — the persistence context, the dispatcher, the template engine, the sender registry, the event bus and the cancellation token — are injected as parameters.

No handler declares an explicit binding source attribute; all binding is convention-based.

Cancellation: every native handler accepts a cancellation token and passes it into its persistence and application calls, so a disconnecting client aborts the work rather than leaving it running.

Dispatch path​

POST /notifications/test/dispatch extends the standard sequence. After the event-type guard, the handler applies its defaults, constructs an event envelope in process, and calls the dispatcher. The dispatcher performs the full processing pipeline — idempotency, staleness, recipient resolution, preference evaluation, rendering, message creation, bounded-retry delivery and audit — before returning an outcome and the created message identifiers, which the handler projects into the response.

The HTTP request therefore remains open for the entire dispatch, including any retry delays.

Broker publish path​

POST /notifications/test/publish diverges after its guard. The handler assembles a metadata dictionary, calls the event bus, and returns immediately on the publish acknowledgement. It does not wait for the consumer to process the event; the consumer handles it asynchronously on the hosted background service. A caller verifying end-to-end behavior through this path must poll a read endpoint afterwards.

When the bus reports failure, the handler returns bare 502.

Persistence​

Handlers use the persistence context directly; there is no repository or unit-of-work indirection. Read paths use no-tracking queries where the result is projected or returned unchanged. Write paths mutate tracked entities and call save explicitly. There is no ambient transaction scope and no explicit transaction in any handler — each save is its own transaction.

The template test live-send path saves twice: once to persist the recipient and message before delivery, and once to persist the delivery attempt and the resulting status afterwards.

Response​

Handlers return through the Results factory: Ok, Created, NotFound, BadRequest and, in one case, a bare status code. Serialization uses the default JSON options; no custom serializer, naming policy or converter is configured.

Classification​

Implemented.

Requires confirmation​

Whether exception-handling middleware is intended to be added, and whether the synchronous dispatch hook is expected to hold the request through retry delays, require confirmation.

See Also​

Keywords​

  • Notification API
  • Request Lifecycle
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Program.cs
  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/shared-kernel/Middleware/CorrelationIdMiddleware.cs
  • microservices/src/notification-service/Application/NotificationDispatcher.cs

Revision Information​

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