Skip to main content

Organization Compatibility APIs

Summary​

Eight compatibility endpoints expose department and designation list, create, update, and delete behavior under the gateway-controlled /api surface.

Audience​

  • Developers maintaining existing clients
  • QA engineers validating route parity
  • Solution architects reviewing ownership boundaries

Reference Content​

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

API inventory​

MethodRoutePurposeAuthenticationTenantRequestResponseMaturitySource path
GET/api/departmentsList departmentsRequires confirmationTenant-scopedNoneDepartmentCompatibilityDto[]Compatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
POST/api/departmentsCreate departmentRequires confirmationRequiredOrganizationCompatibilityDepartmentRequestDepartmentCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
PUT/api/departments/{id}Update departmentRequires confirmationRequiredOrganizationCompatibilityDepartmentRequestDepartmentCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
DELETE/api/departments/{id}Deactivate departmentRequires confirmationRequiredGUID stringStringCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
GET/api/designationsList designationsRequires confirmationTenant-scopedNoneDesignationCompatibilityDto[]Compatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
POST/api/designationsCreate designationRequires confirmationRequiredOrganizationCompatibilityDesignationRequestDesignationCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
PUT/api/designations/{id}Update designationRequires confirmationRequiredOrganizationCompatibilityDesignationRequestDesignationCompatibilityDtoCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
DELETE/api/designations/{id}Deactivate designationRequires confirmationRequiredGUID stringStringCompatibility / Transitionalmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs

Shared boundary​

Bearer support is registered, but endpoint enforcement and authorization are Requires confirmation. Reads use tenant-filtered data; writes require tenant-aware services. Missing tenant behavior is not uniform and is Requires confirmation. IDs must be GUID strings; numeric legacy IDs return 400 when the extracted service handles the route.

List departments​

  • Operation / purpose: GetDepartmentsCompatibility; list departments ordered by name with active-employee counts.
  • Method / route: GET /api/departments; no parameters or body.
  • Response: id, name, code, nullable parentDepartmentId, headUserId, location, clientTenantId, headName, plus isActive, employeeCount.
  • Validation/status: 200 confirmed; other errors and 401/403 Requires confirmation. Side effects: none.
  • Compatibility: plain list; unlike direct lookup, includes inactive rows and count/display fields.
GET /api/departments
Authorization: Bearer <approved-token>
[{"id":"22222222-2222-4222-8222-222222222222","name":"Example Department","code":"EXAMPLE","parentDepartmentId":null,"headUserId":null,"location":null,"isActive":true,"clientTenantId":1001,"headName":null,"employeeCount":0}]

Example error response: no endpoint-specific handled error exists; Requires confirmation.

Create department​

  • Operation / purpose: CreateDepartmentCompatibility; create a tenant department.
  • Method / route: POST /api/departments; no route/query parameters.
  • Body: required name, code; optional GUID-or-null parentDepartmentId, headUserId, location, and nullable isActive.
  • Validation: GUID strings or null; domain validates name/code; code unique per tenant. Source creation does not apply requested isActive, so create-time inactivity is Not implemented by the extracted adapter.
  • Response/status: 200 DTO; 400 invalid ID, validation, or duplicate conflict. Side effects: creates and audits department.
  • Compatibility: monolith and extracted validation/body details can differ.
POST /api/departments
Authorization: Bearer <approved-token>
Content-Type: application/json

{"name":"Example Department","code":"EXAMPLE","parentDepartmentId":null,"headUserId":null,"location":null,"isActive":true}
{"id":"22222222-2222-4222-8222-222222222222","name":"Example Department","code":"EXAMPLE","parentDepartmentId":null,"headUserId":null,"location":null,"isActive":true,"clientTenantId":1001,"headName":null,"employeeCount":0}
"A department with this code already exists."

Update department​

  • Operation / purpose: UpdateDepartmentCompatibility; update department properties and active state.
  • Method / route: PUT /api/departments/{id}; GUID-string id; no query.
  • Body/validation: same request as create; department must exist; GUIDs valid; name/code domain rules; code unique.
  • Response/status: 200 DTO; 400 invalid/validation/conflict; 404 empty body. Side effects: updates and audits department.
  • Compatibility: extracted route requires GUID.
PUT /api/departments/22222222-2222-4222-8222-222222222222
Authorization: Bearer <approved-token>
Content-Type: application/json

{"name":"Example Department Updated","code":"EXAMPLE","parentDepartmentId":null,"headUserId":null,"location":null,"isActive":true}
{"id":"22222222-2222-4222-8222-222222222222","name":"Example Department Updated","code":"EXAMPLE","parentDepartmentId":null,"headUserId":null,"location":null,"isActive":true,"clientTenantId":1001,"headName":null,"employeeCount":0}

Example error response: empty 404 body for a missing department.

Delete department​

  • Operation / purpose: DeleteDepartmentCompatibility; deactivate a department when no active employee is assigned.
  • Method / route: DELETE /api/departments/{id}; GUID-string id; no query/body.
  • Validation: ID valid; department exists; no active employee assignment.
  • Response/status: 200 JSON string Deleted successfully; 400 invalid ID or assignment conflict; 404 empty body.
  • Side effects: deactivates and audits; it is not a physical-delete contract. Compatibility: semantics may differ at the monolith destination.
DELETE /api/departments/22222222-2222-4222-8222-222222222222
Authorization: Bearer <approved-token>
"Deleted successfully"
"Department is assigned to active employees."

List designations​

  • Operation / purpose: GetDesignationsCompatibility; list designations ordered by level and name with active-employee counts.
  • Method / route: GET /api/designations; no parameters/body.
  • Response: id, name, code, nullable departmentId, departmentName, grade, clientTenantId, plus level, isActive, employeeCount.
  • Validation/status: 200; other errors and 401/403 Requires confirmation. Side effects: none.
  • Compatibility: unlike direct lookup, includes inactive rows and display/count fields.
GET /api/designations
Authorization: Bearer <approved-token>
[{"id":"33333333-3333-4333-8333-333333333333","name":"Example Designation","code":"EXAMPLE","departmentId":null,"departmentName":null,"grade":null,"level":1,"isActive":true,"clientTenantId":1001,"employeeCount":0}]

Example error response: no endpoint-specific handled error exists; Requires confirmation.

Create designation​

  • Operation / purpose: CreateDesignationCompatibility; create a tenant designation.
  • Method / route: POST /api/designations; no route/query.
  • Body: required name, code; optional GUID-or-null departmentId, grade, nullable level, isActive.
  • Validation: GUID string or null; domain validates name/code/level; code unique per tenant. Source creation does not apply requested isActive, so create-time inactivity is Not implemented by the extracted adapter.
  • Response/status: 200 DTO; 400 invalid/validation/conflict. Side effects: creates and audits designation.
  • Compatibility: plain DTO, not direct response envelope.
POST /api/designations
Authorization: Bearer <approved-token>
Content-Type: application/json

{"name":"Example Designation","code":"EXAMPLE","departmentId":null,"grade":null,"level":1,"isActive":true}
{"id":"33333333-3333-4333-8333-333333333333","name":"Example Designation","code":"EXAMPLE","departmentId":null,"departmentName":null,"grade":null,"level":1,"isActive":true,"clientTenantId":1001,"employeeCount":0}
"A designation with this code already exists."

Update designation​

  • Operation / purpose: UpdateDesignationCompatibility; update designation fields and active state.
  • Method / route: PUT /api/designations/{id}; GUID-string id; no query.
  • Body/validation: same request as create; designation exists; GUID and domain rules; code unique.
  • Response/status: 200 DTO; 400 invalid/validation/conflict; 404 empty body. Side effects: updates and audits designation.
  • Compatibility: extracted route requires GUID.
PUT /api/designations/33333333-3333-4333-8333-333333333333
Authorization: Bearer <approved-token>
Content-Type: application/json

{"name":"Example Designation Updated","code":"EXAMPLE","departmentId":null,"grade":null,"level":2,"isActive":true}
{"id":"33333333-3333-4333-8333-333333333333","name":"Example Designation Updated","code":"EXAMPLE","departmentId":null,"departmentName":null,"grade":null,"level":2,"isActive":true,"clientTenantId":1001,"employeeCount":0}

Example error response: empty 404 body for a missing designation.

Delete designation​

  • Operation / purpose: DeleteDesignationCompatibility; deactivate a designation.
  • Method / route: DELETE /api/designations/{id}; GUID-string id; no query/body.
  • Validation: valid GUID; designation exists.
  • Response/status: 200 JSON string Deleted successfully; 400 invalid ID; 404 empty body.
  • Side effects: deactivates and audits; not a physical-delete contract. Compatibility: the extracted service does not reject based on employee assignment in this method.
DELETE /api/designations/33333333-3333-4333-8333-333333333333
Authorization: Bearer <approved-token>
"Deleted successfully"
"designation id 'not-a-guid' is not a valid GUID."

Source References​

  • microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
  • microservices/src/employee-service/Application/Organization/Organization.cs
  • Controllers/DepartmentsController.cs
  • Controllers/DesignationsController.cs
  • microservices/scripts/smoke-employee.ps1

See Also​

Keywords​

  • Department compatibility
  • Designation compatibility
  • Transitional organization API

Revision Information​

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