Skip to main content

Notification API Versioning

Summary​

HTTP API versioning is Not implemented. No versioning scheme of any kind governs the Notification API. Two unrelated version concepts exist internally and are documented here so they are not mistaken for API versions.

Audience​

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

Verified absence​

The reviewed source contains none of the following:

  • No API versioning package registration and no AddApiVersioning call.
  • No version segment in any route. Native routes begin directly at their resource prefix; compatibility routes begin at the /api prefix with no version segment following it.
  • No version query parameter, no version request header and no media-type versioning.
  • No ApiVersion attribute, no version set and no version-neutral marker on any endpoint.
  • No deprecation attribute, sunset header or deprecation notice on any route.
  • No versioned Swagger document; a single unversioned document is generated.

A breaking change to any Notification endpoint would therefore reach every caller at once, with no negotiated migration path.

Internal version concepts​

Two fields named "version" exist in the module. Neither is an HTTP API version.

Template version. Template rows carry an integer version scoped to a tenant, key and channel triple. Creating a template computes the next value and inserts a new row; resolution prefers the highest active version. This versions notification content, not the API contract, and it is not selectable by any HTTP parameter — a caller cannot request a specific template version through the API.

Event schema version. The event envelope carries a schema version, and both test hooks set it to a fixed value of one. This describes the shape of a consumed integration event, not an HTTP contract, and it is not accepted from the caller — the hooks hard-code it.

De facto versioning​

The only mechanism resembling versioning is the coexistence of two whole implementations: the legacy monolith surface and the native surface, selected by the gateway toggle. This is a migration arrangement rather than a versioning scheme — the two surfaces are not two versions of one contract, since their identifiers, template models and response shapes differ fundamentally.

See gateway and compatibility for the divergence table.

Classification​

Not implemented.

Requires confirmation​

Whether a versioning scheme is planned before the native surface is exposed to external consumers, and what the deprecation path for the legacy surface will be, require confirmation.

See Also​

Keywords​

  • Notification API
  • Versioning
  • Draft API documentation

Source References​

  • microservices/src/notification-service/Program.cs
  • microservices/src/notification-service/Api/NotificationEndpoints.cs
  • microservices/src/notification-service/Messaging/NotificationEventEnvelope.cs
  • microservices/src/gateway-api/Program.cs

Revision Information​

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