Skip to main content

API Response Models

Summary​

Lifecycle APIs do not share one response envelope. Native Recruitment returns DTOs directly, compatibility adapters preserve monolith-shaped records and messages, HR Operations returns entities or anonymous projections, and Employee Service uses a standard envelope.

Audience​

Developers, QA, support, and solution architects.

Reference Content​

The following response families are verified in the inspected lifecycle implementations.

Success patterns​

SurfaceVerified success response
Native Recruitment commandDirect OfferDto or OnboardingDto with success status
Native Recruitment list/reportDirect list or report DTO
Public offer readReduced public offer DTO
Compatibility workspaceMonolith-shaped anonymous workspace object
Compatibility mutationsRecord projection, message object, or completion result
HR Operations mutationsPersisted task/exit entity
HR Operations access revokeAnonymous processed-count object
HR Operations readsWorkspace object or bounded entity list
Employee createCreated status with standard success envelope
Employee searchSuccess envelope with paged search data
Host service informationStandard shared-kernel envelope
HealthFramework health result

Created responses​

The verified lifecycle-created response is the outbound Employee Service create result. Recruitment onboarding and HR Operations create actions return successful objects rather than a Created response.

Compatibility response risk​

The extracted adapter reconstructs compatibility messages and completion data, but not every internal effect matches the monolith. Response shape therefore cannot be used as proof that a login, organization mapping, bank/KYC persistence, or other side effect occurred.

Sensitive completion response​

Legacy-shaped completion can return login-bootstrap material. Actual values and examples are intentionally excluded. The extracted adapter can construct such response material even while login provisioning remains pending.

Requires confirmation​

  • A target standard response envelope for lifecycle APIs.
  • Compatibility casing and nullability guarantees.
  • Whether sensitive completion response fields should be removed or delivered through another channel.
  • Created-resource location semantics for onboarding, exit, and task creation.

Source References​

  • microservices/src/recruitment-service/Api/EndpointResults.cs
  • microservices/src/recruitment-service/Application/Dtos.cs
  • microservices/src/recruitment-service/Application/Compatibility/CompatContracts.cs
  • microservices/src/recruitment-service/Application/Compatibility/CompatCommands.cs
  • microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
  • microservices/src/shared-kernel/Extensions/EndpointRouteBuilderExtensions.cs
  • Controllers/RecruitmentController.cs
  • Controllers/HrOperationsController.cs

See Also​

Keywords​

  • Response envelope
  • Compatibility result
  • Sensitive response

Revision Information​

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