Joseph Doherty
26ff8d9b4f
Set up repository with legacy .NET Framework 4.8 source (OLD/), new .NET 10 Blazor solution (NEW/), OpenSpec specifications, documentation, and project configuration.
92 lines
5.2 KiB
Markdown
92 lines
5.2 KiB
Markdown
# 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
|