Skip to main content

Notification API Response Models

Summary​

The native API uses four response patterns: serialized persistence entities, inline anonymous projections, a 201 Created with a location, and one bare status code. It does not use a uniform envelope, typed response DTOs, paging metadata or problem details.

Audience​

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

Reference Content​

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

Verified response patterns​

Serialized entities​

Eight endpoints return persistence entities directly: template list, template create and template update; single message read; failed queue; attempts; processed-event lookup; and audit query. The wire shape is whatever the entity declares, including internal fields, and it changes whenever the persistence model changes.

Anonymous projections​

Seven endpoints return an unnamed success projection constructed in the handler: the inbox item list, the read-state result, the retry result, the statistics counts, the template render result, the dispatch outcome and the publish acknowledgement. The small not-found and bad-request bodies are anonymous as well. These have no schema name and cannot be referenced from a generated client.

Collections​

Collection endpoints return a bare JSON array. There is no wrapper object, no total count, no page number and no continuation token. Page size is controlled by a clamped take parameter, so a caller cannot tell whether more records exist beyond the returned page.

Created​

Only template create returns 201. It supplies a location pointing at the new template and the created entity as the body.

Envelope​

Only the service-information endpoint returns the shared ApiResponse<T> envelope with its success flag, message, data, correlation identifier and errors dictionary. Every other endpoint returns its payload unwrapped, so a client cannot rely on one response shape across the surface.

Health report​

The health endpoint returns the framework default health response rather than a service-shaped body.

Status codes in use​

CodeWhere it is returned
200Every successful read and every successful mutation except template create
201Template create only
400The four guard-clause failures
404Record-absent paths, each with a small object carrying a found or processed flag; also framework route-constraint misses
502Test publish only, when the bus reports that publication did not succeed — returned bare, with no body

Verified absence: no endpoint returns 202, 204, 401, 403, 409, 422 or 500 deliberately. The compatibility controllers additionally return 401 when the caller cannot be resolved.

Not-found convention​

Native 404 responses carry a small object echoing the requested identifier plus a boolean flag — found on most endpoints, processed on the idempotency lookup. This is a body, not a bare status, but it is not problem details.

The attempts endpoint is the exception: an unknown message identifier returns 200 with an empty array rather than 404, because the handler queries attempts without first confirming the message exists.

Serialization​

Default JSON serialization applies. No custom naming policy, converter, null-handling option or serializer configuration is registered, so property names follow the framework default camel-casing of the declaring type's members.

Verified absence​

  • No uniform response envelope across the surface.
  • No named response DTO on the native surface.
  • No paging, sorting or filtering metadata on any collection.
  • No ETag, Last-Modified, cache-control or concurrency header.
  • No Produces or ProducesResponseType metadata, so generated documentation infers schemas.
  • No problem-details response anywhere.

Classification​

Partial.

Requires confirmation​

Whether the platform envelope is intended to apply to the whole surface, and whether paging metadata is planned for the collection endpoints, require confirmation.

See Also​

Keywords​

  • Notification API
  • Response Models
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/notification-service/Program.cs
  • microservices/src/contracts/Common/ApiResponse.cs
  • microservices/src/notification-service/Domain/NotificationEntities.cs

Revision Information​

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