Skip to main content

Employee Compatibility APIs

Summary​

Five compatibility endpoints preserve the /api/employees route family while Employee routing can coexist with the monolith. They return a plain legacy-shaped DTO and require GUID identifiers when routed to Employee Service.

Audience​

  • Developers maintaining existing clients
  • QA engineers validating cutover parity
  • Solution architects and support engineers

Reference Content​

The following inventory and endpoint sections define the extracted compatibility employee surface.

API inventory​

MethodRoutePurposeAuthenticationTenantRequestResponseMaturitySource path
GET/api/employeesList employeesRequires confirmationTenant-scopedQueryEmployeeCompatibilityDto[]Compatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
GET/api/employees/{id}Get employeeRequires confirmationTenant-scopedGUID stringEmployeeCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
POST/api/employeesCreate employeeRequires confirmationRequiredEmployeeCompatibilityUpsertRequestEmployeeCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
PUT/api/employees/{id}Update employeeRequires confirmationRequiredEmployeeCompatibilityUpsertRequestEmployeeCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
PATCH/api/employees/{id}/activeSet active stateRequires confirmationRequiredJSON booleanEmployeeCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs

Shared compatibility contract​

The host supports Bearer authentication, but route enforcement and permissions are Requires confirmation. Reads are tenant-filtered; mutation handlers require tenant context. Missing-context behavior is not uniform across this adapter and remains Requires confirmation. Plain 400 strings, empty 404 bodies, and plain DTO success bodies are used.

EmployeeCompatibilityUpsertRequest accepts: name, employeeCode, email, phone, departmentId, designationId, joiningDate, employmentType, reportingManagerId, gender, salaryType, salaryAmount, annualCTC, monthlyCTC, hourlyRate, basicSalaryMonthly, hraMonthly, otherAllowanceMonthly, factoryId, dateOfBirth, attendanceMode, standardDailyHours, overtimeRatePerHour, shortfallDeductionRatePerHour, halfDayBelowHours, absentBelowHours, shiftId, clientTenantId, isActive, panNumber, aadhaarNumber, address, bankName, bankAccountNumber, and ifscCode.

Only name/profile, organization assignment, joining/employment context, gender, date of birth, attendance-mode-as-work-location, and active state are mapped into current Employee commands. Other accepted legacy fields are not persisted by this adapter; their behavior is Transitional.

The complete response shape is:

{"id":"11111111-1111-4111-8111-111111111111","name":"Alex Example","employeeCode":"EMP-EXAMPLE-001","email":"alex@example.com","phone":null,"departmentId":null,"departmentName":null,"designationId":null,"designationName":null,"joiningDate":"2026-07-15","employmentType":"Full-time","reportingManagerId":null,"reportingManagerName":null,"salaryType":"Daily","salaryAmount":0,"annualCTC":null,"monthlyCTC":null,"hourlyRate":null,"basicSalaryMonthly":0,"hraMonthly":0,"otherAllowanceMonthly":0,"compensation":{"employmentMode":"Direct","salaryType":"Daily","salaryAmount":0,"annualCTC":null,"monthlyCTC":null,"hourlyRate":null,"basicSalaryMonthly":0,"hraMonthly":0,"otherAllowanceMonthly":0},"factoryId":1,"dateOfBirth":null,"attendanceMode":"Direct","standardDailyHours":8,"overtimeRatePerHour":0,"shortfallDeductionRatePerHour":0,"halfDayBelowHours":4,"absentBelowHours":1,"shiftId":null,"shift":null,"clientTenantId":1001,"isActive":true,"userId":null,"linkedUser":null,"panNumber":null,"aadhaarNumber":null,"address":null,"bankName":null,"bankAccountNumber":null,"ifscCode":null}

List employees​

  • Operation / purpose: GetEmployeesCompatibility; list tenant-visible employees ordered by display name.
  • Method / route: GET /api/employees. Route/body: none. Query: includeInactive is a non-nullable boolean query parameter; supply false for active records only.
  • Validation/behavior: when true, the adapter does not add its active-only predicate.
  • Response/status: 200 array of compatibility DTOs. Binding errors and 401/403 are Requires confirmation.
  • Side effects: none. Compatibility: gateway destination can be monolith or extracted service.
GET /api/employees?includeInactive=false
Authorization: Bearer <approved-token>

Example success response: an array containing the complete shared compatibility response shown above.

Example error response: no endpoint-specific handled error body exists; framework/gateway failure is Requires confirmation.

Get employee​

  • Operation / purpose: GetEmployeeCompatibility; retrieve one tenant-visible employee.
  • Method / route: GET /api/employees/{id}; id must be a GUID string. Query/body: none.
  • Validation: invalid GUID and legacy numeric IDs return 400.
  • Response/status: 200 compatibility DTO; 400 invalid ID; 404 empty body. 401/403 Requires confirmation.
  • Side effects: none. Compatibility: monolith identifier behavior differs; clients must use GUIDs for extracted routing.
GET /api/employees/11111111-1111-4111-8111-111111111111
Authorization: Bearer <approved-token>

Example success response: the complete shared compatibility response shown above.

"employee id 'not-a-guid' is not a valid GUID."

Create employee​

  • Operation / purpose: CreateEmployeeCompatibility; adapt a legacy-shaped upsert to Employee creation and an optional status change.
  • Method / route: POST /api/employees; no route/query parameters.
  • Body: EmployeeCompatibilityUpsertRequest fields listed above.
  • Validation: organization and manager identifiers must be GUID strings or null; mapped direct rules require employee code, first name derived from name, email, uniqueness, and active references. False isActive maps to Terminated after creation.
  • Response/status: 200 compatibility DTO; 400 invalid ID, validation, conflict, or handled request failure. Side effects: creates an Employee and may apply a second status command; confirmed audit/timeline/outbox side effects occur, without payload documentation.
  • Compatibility: does not return 201 or ApiResponse<T>.
POST /api/employees
Authorization: Bearer <approved-token>
Content-Type: application/json

{"name":"Alex Example","employeeCode":"EMP-EXAMPLE-001","email":"alex@example.com","phone":null,"departmentId":null,"designationId":null,"joiningDate":"2026-07-15","employmentType":"Full-time","reportingManagerId":null,"gender":null,"salaryType":null,"salaryAmount":0,"annualCTC":null,"monthlyCTC":null,"hourlyRate":null,"basicSalaryMonthly":0,"hraMonthly":0,"otherAllowanceMonthly":0,"factoryId":1,"dateOfBirth":null,"attendanceMode":null,"standardDailyHours":8,"overtimeRatePerHour":0,"shortfallDeductionRatePerHour":0,"halfDayBelowHours":4,"absentBelowHours":1,"shiftId":null,"clientTenantId":null,"isActive":true,"panNumber":null,"aadhaarNumber":null,"address":null,"bankName":null,"bankAccountNumber":null,"ifscCode":null}

Example success response: the complete shared compatibility response shown above.

"Employee code already exists for this tenant."

Update employee​

  • Operation / purpose: UpdateEmployeeCompatibility; adapt one legacy-shaped request into profile update plus changed department, manager, and status commands.
  • Method / route: PUT /api/employees/{id}; GUID-string id; no query.
  • Body/validation: same upsert body and rules as create; employee must exist; email remains unique; designation and changed assignments must be valid/active; self-manager is rejected.
  • Response/status: 200 compatibility DTO; 400 validation/invalid ID; 404 empty body. Side effects: may perform several sequential commands and their confirmed audit/timeline/outbox recording.
  • Compatibility: the combined legacy operation is not atomic across a single command boundary; clients should treat partial failure behavior as Requires confirmation.
PUT /api/employees/11111111-1111-4111-8111-111111111111
Authorization: Bearer <approved-token>
Content-Type: application/json

{"name":"Alex Example","employeeCode":"EMP-EXAMPLE-001","email":"alex.updated@example.com","phone":null,"departmentId":null,"designationId":null,"joiningDate":"2026-07-15","employmentType":"Full-time","reportingManagerId":null,"gender":null,"salaryType":null,"salaryAmount":0,"annualCTC":null,"monthlyCTC":null,"hourlyRate":null,"basicSalaryMonthly":0,"hraMonthly":0,"otherAllowanceMonthly":0,"factoryId":1,"dateOfBirth":null,"attendanceMode":null,"standardDailyHours":8,"overtimeRatePerHour":0,"shortfallDeductionRatePerHour":0,"halfDayBelowHours":4,"absentBelowHours":1,"shiftId":null,"clientTenantId":null,"isActive":true,"panNumber":null,"aadhaarNumber":null,"address":null,"bankName":null,"bankAccountNumber":null,"ifscCode":null}

Example success response: the complete shared compatibility response shown above with the updated email.

Example error response: an empty 404 body when the employee is not found.

Set employee active state​

  • Operation / purpose: SetEmployeeActiveCompatibility; map true to Active and false to Terminated.
  • Method / route: PATCH /api/employees/{id}/active; GUID-string id; no query.
  • Body: a raw JSON boolean, not an object.
  • Validation: GUID required; employee must exist; status command rules apply.
  • Response/status: 200 compatibility DTO; 400 invalid ID/validation; 404 empty body. Side effects: status change plus confirmed audit/timeline/outbox recording.
  • Compatibility: this boolean contract cannot express OnLeave or Suspended; use the direct status endpoint for those values.
PATCH /api/employees/11111111-1111-4111-8111-111111111111/active
Authorization: Bearer <approved-token>
Content-Type: application/json

false

Example success response: the complete shared compatibility response shown above with "isActive": false.

"employee id 'not-a-guid' is not a valid GUID."

Source References​

  • microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
  • microservices/src/employee-service/Application/Commands/EmployeeApplicationCommands.cs
  • microservices/src/employee-service/Application/Validators/EmployeeCommandValidators.cs
  • Controllers/LaborController.cs
  • microservices/scripts/smoke-employee.ps1

See Also​

Keywords​

  • Compatibility employees
  • Legacy-shaped DTO
  • Transitional API

Revision Information​

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