Skip to main content

API Versioning

Summary​

No explicit lifecycle API versioning strategy was found. The inspected hosts do not register an API-versioning framework, route versions, version headers, media-type versions, deprecation metadata, or versioned OpenAPI documents.

Audience​

Developers, QA, support, product owners, and solution architects.

Current evolution mechanism​

The implementation evolves through separate native and compatibility route families plus gateway-selected ownership. This is a migration mechanism, not formal API versioning. Compatibility classes preserve existing portal shapes while translating to extracted commands.

Verified absence​

  • No API version service registration
  • No controller or endpoint version attributes
  • No mapped version sets
  • No version request reader
  • No version-specific OpenAPI document configuration
  • No lifecycle deprecation or sunset metadata
  • No compatibility retirement version

Risk​

Route stability can conceal behavioral change when gateway ownership changes. Without a declared version policy, clients cannot infer side-effect, authorization, validation, or response-parity changes from the external contract.

Requires confirmation​

  • Whether versioning will be route, header, or media-type based.
  • Compatibility support duration and deprecation notice requirements.
  • Breaking-change governance and consumer notification ownership.
  • OpenAPI version publication and contract-test strategy.

Source References​

  • microservices/src/recruitment-service/Program.cs
  • microservices/src/recruitment-service/Api/RecruitmentEndpoints.cs
  • microservices/src/recruitment-service/Api/RecruitmentCompatEndpoints.cs
  • microservices/src/gateway-api/Program.cs
  • Controllers/RecruitmentController.cs
  • Controllers/HrOperationsController.cs

See Also​

Keywords​

  • Unversioned API
  • Compatibility migration
  • Deprecation policy

Revision Information​

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