# Implement Web API

## Summary

Implement the REST API layer and real-time SignalR hub for the JDE Scoping Tool, providing HTTP endpoints for search management, lookup operations, file upload/download, and authentication. This phase creates the web-facing interface that connects the Blazor WebAssembly client to the backend search processing and data access layers.

## Scope

### In Scope

- `AuthController` with login, logout, and current user endpoints
- `SearchController` with CRUD operations and result downloads
- `LookupController` with autocomplete APIs for items, profit centers, work centers, and operators
- `FileController` with Excel upload/download for bulk data import
- `StatusHub` SignalR hub for real-time status and search updates
- `IAuthService` interface with LDAP and fake authentication implementations
- `LdapAuthService` using `System.DirectoryServices.Protocols` (cross-platform)
- `FakeAuthService` for development mode authentication bypass
- `LdapOptions` and `AuthOptions` configuration classes
- `UserInfo` model (renamed from legacy `LDAPEntry`)
- API model DTOs (`LoginRequest`, `AuthResult`, `FileUploadResult<T>`, etc.)
- Cookie-based session management with ASP.NET Core authentication
- Service registration extension methods (`AddWebApi`, `AddAuthentication`)
- OpenAPI/Swagger documentation
- Unit tests with xUnit, Shouldly, and NSubstitute

### Out of Scope

- Blazor WebAssembly client implementation (Phase 9)
- Background worker service (Phase 5: implement-data-sync)
- Search execution logic (Phase 6: implement-search-processing)
- Excel export generation (Phase 7: implement-excel-export)
- Database schema changes (Phase 1: migrate-database-schema)
- Rate limiting and advanced security (future enhancement)

## Motivation

The Web API layer is the bridge between the Blazor WebAssembly client and the backend services. This phase delivers:

- **REST API Endpoints**: Standard HTTP APIs for search, lookup, and file operations
- **Real-Time Updates**: SignalR hub for live status updates during search processing
- **Cross-Platform Authentication**: LDAP authentication using `System.DirectoryServices.Protocols` (not the Windows-only `System.DirectoryServices`)
- **Development Mode Support**: Fake authentication for local development without LDAP server
- **OpenAPI Documentation**: Auto-generated API documentation for Blazor client development

## Acceptance Criteria

1. `AuthController` implements login, logout, and current user endpoints
2. `SearchController` implements all CRUD operations with proper authorization
3. `LookupController` implements autocomplete APIs without authorization (public access)
4. `FileController` implements Excel upload/download with caching
5. `StatusHub` broadcasts status and search updates to all connected clients
6. `LdapAuthService` authenticates against LDAP with group membership verification
7. `FakeAuthService` accepts any credentials when `AuthOptions.UseFakeAuth = true`
8. Cookie authentication configured with proper timeout and no redirect on 401
9. All protected endpoints return HTTP 401 (not redirect) for Blazor WASM compatibility
10. SignalR hub maps to `/hubs/status` endpoint
11. OpenAPI documentation generated via Swagger
12. All services registered via `AddWebApi()` extension method
13. Unit tests achieve >80% code coverage for controllers and services
14. `openspec validate implement-web-api --strict` passes

## Dependencies

| Phase | Dependency | Type |
|-------|------------|------|
| Phase 4: implement-data-access | `ILotFinderRepository` for lookups and search storage | Required |
| Phase 5: implement-data-sync | Worker service publishes status updates (soft dependency) | Soft |
| Phase 6: implement-search-processing | Search execution produces results | Required |
| Phase 7: implement-excel-export | `IExcelExportService` for file downloads | Required |

**Note:** Controllers can be implemented with interface dependencies, allowing parallel development with mock implementations for testing.

## Risks

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| LDAP connectivity issues | Medium | High | Implement `FakeAuthService` for development; add connection retry logic |
| `System.DirectoryServices.Protocols` complexity | Medium | Medium | Follow Microsoft documentation; create comprehensive LDAP integration tests |
| SignalR connection management | Low | Medium | Use ASP.NET Core SignalR defaults; implement client reconnection in Blazor |
| Cookie authentication with Blazor WASM | Low | Medium | Configure `SuppressAuthenticationChallengeOnUnauthorized`; test cross-origin scenarios |
| File upload size limits | Low | Low | Configure `IFormFile` limits in `Program.cs`; document limits |
| Memory cache expiration for file downloads | Low | Low | Use 1-minute expiration matching legacy; remove after download |

## Related Specs

- `web-api-auth/spec.md` - Base specification for Web API and authentication
- `domain-models/spec.md` - Domain entities used by controllers
- `data-access/spec.md` - Repository interfaces for data operations
- `search-processing/spec.md` - Search processing service interfaces
- `excel-export/spec.md` - Excel export service for result downloads