Skip to main content

DWD API Implementation Plan

Overview​

This document outlines the comprehensive implementation plan for the DWD API development, building upon the completed NetworkManager section-based architecture. The API will serve as the backend/middleware orchestrator for the HydroTrek DWD Suite, providing RESTful endpoints for all EPANET network data and configuration.

Project Context​

✅ Completed Foundation​

  • NetworkManager Migration: Section-based architecture with 14 new parsers
  • Database Schema: All new EN2Models with proper constraints
  • Data Processing: Comprehensive EPANET input file parsing and validation
  • V&V System: Data validation and verification capabilities

🎯 Current Phase: API Development​

  • Target: Complete RESTful API for all EPANET network data
  • Duration: Estimated 40-60 hours (5-8 days)
  • Dependencies: NetworkManager completion ✅

Implementation Phases​

Phase 1: Core Infrastructure Setup (Day 1 - 8 hours)​

Step 1.1: Project Structure & Dependencies (2 hours)​

  • Verify existing project structure
  • Update NuGet packages and dependencies
  • Configure Entity Framework Core for new models
  • Set up dependency injection for new services

Step 1.2: Database Context Integration (2 hours)​

  • Integrate EN2PostgresContext with existing API context
  • Configure database migrations for new tables
  • Set up connection string management
  • Test database connectivity

Step 1.3: Base Controller Infrastructure (2 hours)​

  • Create base controller classes with common functionality
  • Implement standard CRUD operations template
  • Set up error handling and logging
  • Configure Swagger/OpenAPI documentation

Step 1.4: Response DTOs & Models (2 hours)​

  • Create response DTOs for all 14 new models
  • Implement mapping between entities and DTOs
  • Set up validation attributes
  • Create request/response models

Phase 2: Core Entity Controllers (Day 2-3 - 16 hours)​

Step 2.1: Pattern & Curve Controllers (4 hours)​

  • PatternController - Time-varying data patterns
    • CRUD operations for Pattern entities
    • Array manipulation for multipliers
    • Validation for pattern data
  • DataCurveController - Pump and tank curves
    • CRUD operations for DataCurve entities
    • Point manipulation methods
    • Min/max calculation endpoints

Step 2.2: Configuration Controllers (4 hours)​

  • TimeParametersController - Simulation timing
    • CRUD operations with scenario support
    • Network defaults endpoints (ScenarioId = null)
    • Scenario-specific overrides
  • OptionsController - Analysis configuration
    • CRUD operations with scenario support
    • Network defaults endpoints
    • EPANET option validation

Step 2.3: Demand & Source Controllers (4 hours)​

  • DemandController - Multiple demand categories
    • CRUD operations with junction-based queries
    • LIST endpoint for junction demands
    • Category-based filtering
  • SourceController - Water quality sources
    • CRUD operations with node-based queries
    • LIST endpoint for node sources
    • Source type validation

Step 2.4: Reaction & Mixing Controllers (4 hours)​

  • ReactionController - Chemical reactions
    • CRUD operations for reaction entities
    • LIST endpoint with filtering
    • Global and object-specific reactions
  • TankMixingController - Tank mixing models
    • CRUD operations (one per tank)
    • Mixing model validation
    • Fraction calculation endpoints

Phase 3: Advanced Entity Controllers (Day 4-5 - 16 hours)​

Step 3.1: Energy & Emitter Controllers (4 hours)​

  • EnergyController - Energy analysis
    • CRUD operations with scenario/pump support
    • Global and pump-specific configurations
    • Network defaults endpoints
  • EmitterController - Pressure-dependent demands
    • CRUD operations with node-based queries
    • LIST endpoint for node emitters
    • Coefficient validation

Step 3.2: Leakage & Quality Controllers (4 hours)​

  • LeakageController - Pipe leakage modeling
    • CRUD operations with link-based queries
    • LIST endpoint for link leakage
    • Crack area and expansion rate validation
  • QualityController - Initial water quality
    • CRUD operations with scenario support
    • Node-based quality settings
    • Network defaults and scenario overrides

Step 3.3: Status & Report Controllers (4 hours)​

  • StatusController - Link status configuration
    • CRUD operations with scenario support
    • Link-based status settings
    • Network defaults and scenario overrides
  • ReportController - Output reporting options
    • CRUD operations with scenario support
    • Report configuration management
    • Output format validation

Step 3.4: Bulk Operations & Advanced Features (4 hours)​

  • Bulk import/export endpoints
  • Batch processing capabilities
  • Advanced querying and filtering
  • Performance optimization

Phase 4: Integration & Testing (Day 6 - 8 hours)​

Step 4.1: API Testing (4 hours)​

  • Unit tests for all controllers
  • Integration tests with database
  • API endpoint validation
  • Error handling verification

Step 4.2: Documentation & Deployment (4 hours)​

  • Complete Swagger/OpenAPI documentation
  • API usage examples
  • Deployment configuration
  • Performance testing

Technical Specifications​

API Architecture​

  • Framework: ASP.NET Core 8.0
  • Architecture: RESTful Web API
  • Database: PostgreSQL with Entity Framework Core
  • Documentation: Swagger/OpenAPI 3.0
  • Authentication: JWT Bearer tokens (future enhancement)

Controller Structure​

[ApiController]
[Route("api/[controller]")]
public class PatternController : ControllerBase
{
    // Standard CRUD operations
    [HttpGet]
    public async Task<ActionResult<IEnumerable<PatternDto>>> GetPatterns()

    [HttpGet("{id}")]
    public async Task<ActionResult<PatternDto>> GetPattern(string id)

    [HttpPost]
    public async Task<ActionResult<PatternDto>> CreatePattern(CreatePatternRequest request)

    [HttpPut("{id}")]
    public async Task<IActionResult> UpdatePattern(string id, UpdatePatternRequest request)

    [HttpDelete("{id}")]
    public async Task<IActionResult> DeletePattern(string id)

    // Specialized operations
    [HttpGet("{id}/multipliers")]
    public async Task<ActionResult<double[]>> GetMultipliers(string id)

    [HttpPut("{id}/multipliers")]
    public async Task<IActionResult> UpdateMultipliers(string id, UpdateMultipliersRequest request)
}

Response DTOs​

public class PatternDto
{
    public string Id { get; set; }
    public string Description { get; set; }
    public double[] Multipliers { get; set; }
    public DateTime CreatedAt { get; set; }
    public DateTime? ModifiedAt { get; set; }
}

public class CreatePatternRequest
{
    [Required]
    [MaxLength(31)]
    public string Id { get; set; }

    [MaxLength(255)]
    public string Description { get; set; }

    [Required]
    public double[] Multipliers { get; set; }
}

Database Integration​

Entity Framework Configuration​

  • Use existing EN2PostgresContext
  • Configure relationships and constraints
  • Set up proper indexing for performance
  • Handle composite keys and nullable scenarios

Migration Strategy​

  • Create new migrations for API-specific tables
  • Preserve existing data integrity
  • Test migration scripts thoroughly
  • Rollback procedures documented

Error Handling & Validation​

Standard Error Responses​

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "One or more validation errors occurred.",
        "details": [
            {
                "field": "Id",
                "message": "The Id field is required."
            }
        ]
    }
}

Validation Rules​

  • Required field validation
  • Length and format constraints
  • Business rule validation
  • EPANET-specific validation

Performance Considerations​

Optimization Strategies​

  • Pagination for large result sets
  • Caching for frequently accessed data
  • Database query optimization
  • Async/await patterns throughout

Response Time Targets​

  • Simple CRUD operations: < 100ms
  • Complex queries: < 500ms
  • Bulk operations: < 2 seconds
  • Large dataset exports: < 10 seconds

Security Considerations​

Authentication & Authorization​

  • JWT token-based authentication (future)
  • Role-based access control
  • API key management
  • Rate limiting

Data Protection​

  • Input sanitization
  • SQL injection prevention
  • XSS protection
  • HTTPS enforcement

Testing Strategy​

Unit Testing​

  • Controller action testing
  • Service layer testing
  • Repository pattern testing
  • Validation testing

Integration Testing​

  • Database integration tests
  • API endpoint testing
  • End-to-end workflow testing
  • Performance testing

Documentation Requirements​

API Documentation​

  • Complete Swagger/OpenAPI specification
  • Request/response examples
  • Error code documentation
  • Authentication requirements

Developer Documentation​

  • Setup and installation guide
  • Development environment configuration
  • Code style guidelines
  • Contributing guidelines

Deployment & DevOps​

Deployment Strategy​

  • Docker containerization
  • Environment-specific configurations
  • Database migration automation
  • Health check endpoints

Monitoring & Logging​

  • Application performance monitoring
  • Error tracking and alerting
  • Request/response logging
  • Database performance monitoring

Success Criteria​

Functional Requirements​

  • All 14 controllers implemented with full CRUD
  • Proper error handling and validation
  • Complete API documentation
  • Database integration working
  • Performance targets met

Quality Requirements​

  • 90%+ code coverage in unit tests
  • All integration tests passing
  • Security vulnerabilities addressed
  • Documentation complete and accurate
  • Code review approved

Risk Mitigation​

Technical Risks​

  • Database Performance: Implement proper indexing and query optimization
  • API Versioning: Plan for future API changes and backward compatibility
  • Scalability: Design for horizontal scaling and load balancing

Project Risks​

  • Scope Creep: Maintain focus on core functionality
  • Timeline Delays: Build in buffer time for complex features
  • Integration Issues: Test early and often with existing components

Next Steps​

  1. Review and approve this implementation plan
  2. Set up development environment and dependencies
  3. Begin Phase 1 with core infrastructure setup
  4. Establish testing framework early in development
  5. Regular progress reviews and plan adjustments as needed

Document Version: 1.0 Created: [Current Date] Last Updated: [Current Date] Status: Ready for Implementation Estimated Duration: 40-60 hours (5-8 days)

Last updated on by Jake, Cursor