Skip to main content

Employee API Overview

Summary​

Employee Service uses ASP.NET Core Minimal APIs to expose employee management, search, history, and organization lookup contracts. A second surface preserves monolith-shaped compatibility contracts, while a small internal group reports foundation metadata.

Audience​

  • API consumers and backend developers
  • QA engineers and solution architects
  • Support engineers diagnosing safe HTTP outcomes

Overview​

The API is organized by route group and response convention rather than by an explicit version. The sections below describe responsibilities, request context, versioning, and runtime discovery.

Responsibilities and groups​

The direct /employee group invokes application command and query handlers and returns ApiResponse<T>. The /api group adapts legacy-shaped contracts and returns plain JSON or plain error bodies. The /api/employee-domain group reports foundation metadata and is not employee CRUD.

Context and response conventions​

Direct handlers obtain tenant context before tenant-scoped work and return a correlation identifier in ApiResponse<T>. Compatibility endpoints use tenant-filtered service data but do not use the direct response envelope. See Authentication and context and Response and error model.

API versioning​

No route version segment, version header, or API-versioning registration was found. Current versioning status is Not implemented. Compatibility does not mean deprecated: the source does not mark these routes deprecated.

Runtime OpenAPI discovery​

Employee Service registers endpoint discovery, Swagger generation, and Swagger UI. In an approved running environment, developers can use the runtime Swagger UI or its generated specification at the service's published gateway location. The exact environment URL is deployment-specific and is Requires confirmation.

No committed Employee OpenAPI document was found. No XML documentation generation setting was found in the Employee Service project, and the Minimal API mappings provide names and tags but not complete request/response metadata. Runtime output is therefore useful for discovery but is not a complete replacement for these reviewed contracts.

Source References​

  • microservices/src/employee-service/Program.cs
  • microservices/src/employee-service/Api/Endpoints.cs
  • microservices/src/employee-service/Api/EmployeeDirectEndpoints.cs
  • microservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.cs
  • microservices/src/employee-service/employee-service.csproj

See Also​

Keywords​

  • Minimal APIs
  • Runtime OpenAPI
  • Employee routes

Revision Information​

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