API Enhancements & Features

Component: DWD API (ASP.NET Core) Period: October 2025 Status: ✅ Complete Purpose: Document API improvements and enhanced features

---

Table of Contents

1. Aggregator Enhancements
2. Property Embedding
3. Usability Improvements
4. Quick Reference

---

1. Aggregator Enhancements

1.1 Quality Aggregation Endpoint ✅

New Endpoint: /api/Aggregate/Qual

Features:

• Quality aggregation across all entity types
• Multiple aggregators in single call
• Entity type filtering (optional)
• Timestamp support

Supported Attributes:

• age - Water age
• chlorine - Chlorine concentration
• tr1 - Trace element 1
• conductivity - Electrical conductivity
• thm - Trihalomethanes

Example:

GET /api/Aggregate/Qual?aggregator=avg,min,max&attribute=chlorine&scenarioId=1

Response:
{
  "values": {
    "avg": 0.52,
    "min": 0.12,
    "max": 0.95
  },
  "unit": "mg/L",
  "metadata": {
    "aggregators": ["avg", "min", "max"],
    "attribute": "chlorine",
    "scenarioId": 1,
    "decimalPrecision": 2
  }
}

1.2 Entity Type Inference ✅

Feature: Automatic entity type detection based on attributes

How it Works:

• Backend determines entity types that support requested attribute
• Automatically queries appropriate tables
• Returns aggregated results across all applicable entities

Example:

GET /api/Aggregate/Qual?aggregator=avg&attribute=age&scenarioId=1
# Automatically aggregates across: Junctions, Tanks, Reservoirs, Pipes, Pumps, Valves

1.3 Cross-Table Aggregation ✅

Feature: Aggregate across multiple entity types for compatible attributes

Benefits:

• Single API call for network-wide statistics
• Automatic table union
• Consistent aggregation logic
• Efficient queries

1.4 Array Aggregator Support ✅

Feature: Request multiple aggregations in a single API call

Example:

GET /api/Aggregate/Qual?aggregator=avg,min,max,sum,count&attribute=chlorine&scenarioId=1

Response:
{
  "values": {
    "avg": 0.52,
    "min": 0.12,
    "max": 0.95,
    "sum": 125.4,
    "count": 241
  }
}

---

2. Property Embedding

2.1 Strategy

Principle: Frontend doesn't know about LinkProperty/NodeProperty tables.

Implementation:

• Properties embedded in DTOs via JOIN operations
• Single API call returns complete entity data
• Backend handles table complexity

2.2 Pump Properties Embedding

Properties Included:

• InitStatus (4) - Initial status (OPEN/CLOSED)
• InitSetting (5) - Initial speed setting
• Pattern (15) - Demand pattern reference
• HCurve (19) - Head curve reference
• ECurve (20) - Efficiency curve reference
• ECost (21) - Energy cost
• EPattern (22) - Energy price pattern

Response Example:

{
  "id": "Pump-1",
  "fromNode": "J-100",
  "toNode": "J-200",
  "initStatus": 1,
  "initStatusDisplay": "Open",
  "initSetting": 1.0,
  "pattern": 5,
  "hCurve": 10,
  "eCost": 0.05,
  "eCurve": 3,
  "ePattern": 2
}

2.3 Valve Properties Embedding

Properties:

• InitStatus (4) - Initial status
• Status (computed) - Current status
• Setting - Valve setting

2.4 Tank Properties Embedding

Properties:

• InitQual (4) - Initial quality
• TankKBulk (23) - Tank bulk reaction coefficient
• Mixing model and fraction

Response Example:

{
  "id": "T-1",
  "initQual": 0.5,
  "tankKBulk": -0.5,
  "mixingModel": 0,
  "mixingModelDisplay": "Mixed (MIXED)",
  "mixingFraction": 0.0
}

---

3. Usability Improvements

3.1 Display Fields Added

Enhancements:

• ✅ InitStatusDisplay - Human-readable status ("Open", "Closed")
• ✅ MixingModelDisplay - Mixing model description
• ✅ ValveTypeDisplay - Valve type description
• ✅ LinkTypeDisplay - Link type description

3.2 Nullable Improvements

Pipes InitStatus:

• Changed to nullable (null if not explicitly set)
• Only returns value if present in [STATUS] section
• Distinguishes between "not set" and "default"

Tank VolCurve:

• Returns null (not 0) when no volume curve
• Clearer indication of absence

3.3 Removed Redundant Fields

Cleaned up:

• ❌ Removed Index from Junction responses (redundant with Id)
• ❌ Removed Index from Reservoir responses
• ✅ Restored ECurve to Pump (efficiency curve, not energy curve)

3.4 Enum Mapping Service

Enhanced with:

• EN_LinkStatusType mapping (0=Closed, 1=Open, 2=Active)
• EN_LinkType mapping (PRV, PSV, FCV, TCV, PBV, GPV)
• Support for status value 2 ("Active" for regulating valves)

---

4. Quick Reference

4.1 API Update Pattern

Standard Pattern for Property Embedding:

// 1. Get entity
var entity = await _context.EntityTable.FindAsync(id);

// 2. Get properties
var props = await _context.PropertyTable
    .Where(p => p.EntityId == id)
    .ToDictionaryAsync(p => p.PropertyId, p => p.PropertyValue);

// 3. Map to DTO with embedded properties
return MapToDto(entity, props);

4.2 Controllers Modified

Controller	Changes	Status
PumpController	Property embedding	✅ Complete
ValveController	Property embedding	✅ Complete
TankController	Property embedding + mixing	✅ Complete
PipeController	Property embedding (KWall, InitStatus)	✅ Complete
EnergyController	Removed ScenarioId	✅ Complete
ReactionController	Removed ScenarioId	✅ Complete

4.3 DTOs Modified

DTO	Changes	Status
PumpDto	Added 7 properties + displays	✅ Complete
ValveDto	Added Status properties	✅ Complete
TankDto	Added 3 properties + mixing	✅ Complete
PipeDto	Added KWall, InitStatus (nullable)	✅ Complete
EnergyDto	Simplified (removed pump refs)	✅ Complete
ReactionDto	Simplified (removed ScenarioId)	✅ Complete

---

Summary

✅ Features Delivered:

• Quality aggregation endpoint
• Enhanced aggregator support (multiple in one call)
• Property embedding in DTOs
• Cross-table aggregation
• Entity type inference
• Display field enhancements
• Nullable improvements
• Enum mapping service

✅ Benefits:

• Simplified frontend integration
• Single API calls for complete data
• Better user experience
• Consistent API design
• Hidden complexity from frontend
• Improved performance
• Better maintainability

✅ Quality:

• All changes tested
• User feedback incorporated
• Documentation complete
• Production ready

---

Related Documentation:

• Property Embedding Strategy: API_Property_Embedding_Strategy.md
• DTO Inheritance Analysis: DTO_Inheritance_Analysis.md
• API Endpoints: API_Endpoints_Reference.md
• Quick Reference: Available in Swagger UI

---

Status: ✅ Complete and Production Ready Last Updated: October 2025