Skip to main content

Notification API Validation Catalog

Summary​

Validation is entirely hand-written guard clauses in handler bodies plus route constraints. No validation framework, filter or attribute is registered anywhere on the Notification API.

Audience​

Engineers, QA, architects, support and security reviewers.

Reference Content​

The verified reference material for this topic is set out in the sections below.

Validation pipeline​

Route validation​

Route constraints are the only declarative validation present.

  • The guid constraint appears on every single-record route: the read-state action, template update, template test, single-message read, attempts, retry and the processed-event lookup.
  • A non-GUID segment fails route matching and produces a framework 404 before any handler runs — not a 400.
  • The monolith compatibility routes use integer identifiers with no explicit constraint, and the template routes key on an unconstrained string.

Request validation​

Every request-level check is an explicit guard in the handler body. There are exactly four.

EndpointCheckFailure
GET /notifications/myrecipientRef must be non-blank400 with a message object
POST /notification-templatestemplateKey and channel must be non-blank400 with a message object
POST /notification-templateschannel must be a known channel400 with a message object enumerating known channels
POST /notifications/test/dispatch and /test/publisheventType must be non-blank400 with a message object

All four use a blank-or-null string test, so whitespace-only values are rejected alongside empty and missing ones.

Range clamping​

Four collection endpoints clamp a caller-supplied page size rather than rejecting an out-of-range value: the inbox and the failed queue clamp to 1–500 with a default of 100, and the audit query clamps to 1–1000 with a default of 200. An out-of-range request succeeds with a clamped result instead of returning 400.

Domain validation​

Domain-level checks are minimal at the API boundary. The channel value on template create is normalized and membership-tested against the known channel set. The template test endpoint requires a destination address before taking the live-send path, treating a missing address as a request for a render-only preview rather than an error.

The template engine renders tolerantly: unknown placeholders do not raise a validation failure.

Persistence validation​

Constraints declared on the persistence model — required columns, lengths and indexes — are enforced by the database at save time. No handler pre-checks them, and no handler catches the resulting exception, so a constraint violation surfaces as an unhandled exception rather than a validated 400.

Notably, template create does not pre-check for a conflicting row; it computes the next version and relies on that arithmetic to avoid collision.

Missing validation (verified)​

  • No FluentValidation, no AddValidation, no endpoint filter and no validation middleware is registered.
  • No DTO declares a data-annotation attribute, a required modifier, or a length, range or format constraint.
  • No email or phone format check exists on the destination address accepted by the template test endpoint.
  • No locale, template-key format, or template-content check exists.
  • No payload schema is enforced on the free-form JSON accepted by the test hooks.
  • No maximum body size, no content-type restriction and no rate limit is declared on any endpoint.
  • No validation-error response uses the problem-details format; failures return anonymous objects with a single message field.

Classification​

Partial.

Requires confirmation​

Whether a validation framework is planned, and whether clamping rather than rejecting out-of-range page sizes is intentional, require confirmation.

See Also​

Keywords​

  • Notification API
  • Validation
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/notification-service/Infrastructure/NotificationDbContext.cs
  • microservices/src/notification-service/Domain/NotificationEntities.cs
  • microservices/src/notification-service/Application/TemplateEngine.cs

Revision Information​

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