Employee API Compatibility and Routing

Summary

The gateway supports coexistence between monolith Employee routes and extracted Employee Service compatibility routes. Route selection is controlled operationally; exact internal configuration names are intentionally excluded.

Audience

• API consumers and QA engineers
• Solution architects and platform operators
• Backend developers planning cutover

Routing model

The compatibility prefixes are employees, departments, and designations. When the Employee cutover is selected, the gateway sends those /api prefixes to Employee Service; otherwise it sends them to the monolith. A separate shadow route permits direct Employee Service exercise without changing the compatibility destination. It is an operational test seam, not a stable client contract.

Contract differences

Concern	Direct surface	Compatibility surface
Prefix	/employee	/api
Response	ApiResponse<T>	Plain legacy-shaped DTO/list/string
Identifiers	GUID route constraints	GUID strings; legacy numeric IDs are rejected by extracted compatibility endpoints
Create status	201	200
Employee update	Focused direct DTO; assignment changes have dedicated commands	Combined legacy-shaped upsert adapted to several commands
Organization	Read-only lookups	Department/designation create, update, delete
Maturity	Primary	Compatibility / Transitional

Monolith controllers still expose numeric identifier routes and some additional aliases or operations. Employee Service compatibility endpoints preserve only the documented /api/employees, /api/departments, and /api/designations contract subset. Therefore, routing cutover can expose identifier, validation, status, and body-shape differences. Clients must validate parity and avoid depending on undocumented aliases.

Cutover and rollback

Conceptually, operators validate compatibility parity, enable the extracted destination, observe safe service signals, and retain the ability to restore monolith routing. Exact operational controls are restricted. Cutover readiness and rollback approval are Requires confirmation.

Source References

• microservices/src/gateway-api/Program.cs
• microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
• Controllers/LaborController.cs
• Controllers/DepartmentsController.cs
• Controllers/DesignationsController.cs
• microservices/scripts/smoke-employee.ps1

Related Articles

• Gateway interaction
• Architecture request routing
• Organization overview

See Also

• Testing guide
• Compatibility employees
• Compatibility organization

Keywords

• Compatibility API
• Gateway cutover
• Shadow route

Revision Information

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