Skip to main content

SWMM API Documentation

This directory contains comprehensive documentation for all controllers in the SWMM API ASP.NET application.

Overview​

The SWMM API provides a comprehensive REST API for managing Storm Water Management Model (SWMM) simulations, scenarios, and data. The API is built on ASP.NET Core and integrates with Azure Storage services for data persistence and retrieval.

Architecture​

The API follows a layered architecture with controllers handling HTTP requests, services managing business logic, and Azure Storage providing data persistence.

Data Storage Architecture​

Azure Blob Storage​

  • networkmodel: Network definitions (nodes, links)
  • swmm-output: Simulation results by timestep
  • radar-images: Weather radar imagery
  • swmm-input: Input files and model data

Azure Table Storage​

  • Runs: Simulation run metadata and status
  • Inputs: Scenario and input data
  • SystemOutput: System-wide time series data
  • NodeOutput: Node time series data
  • LinkOutput: Link time series data
  • SubCatchOutput: Subcatchment time series data
  • SensorsXRef: Sensor cross-references
  • SensorData: Sensor time series data
  • AttributeXRef: Attribute definitions
  • Errors: Error logging

Controllers Overview​

Authentication & Authorization​

Core Data Management​

Scenario & Run Management​

Sensor & Monitoring​

Utilities​

Data Flow Patterns​

Simulation Workflow​

Data Retrieval Pattern​

Common Data Models​

Time Series Data​

Most controllers return time series data in one of these formats:

Unix Timestamp Format:

[
  {
    "simUnixTime": 1700000000000,
    "value": 25.5
  }
]

Array Format:

[[1700000000000, 25.5], [1700000015000, 26.1]]

CSV Format:

"1.2,1.5,1.8,2.1,1.9,1.6,1.3,1.1,0.9,0.7"

Network Elements​

  • Nodes: Junctions, outfalls, storage units, dividers
  • Links: Conduits, channels, orifices, weirs, pumps
  • Subcatchments: Drainage areas with runoff characteristics

Authentication & Security​

JWT Authentication​

  • Tokens expire after 5 minutes
  • HMAC-SHA512 signature algorithm
  • Stateless authentication

External API Integration​

  • Esri ArcGIS: OAuth client credentials flow
  • Azure Maps: Subscription key authentication

Error Handling​

Standard Error Responses​

  • 400 Bad Request: Validation errors
  • 401 Unauthorized: Authentication required
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server errors

Error Logging​

All errors are logged to Azure Table Storage with:

  • Error message
  • Stack trace
  • Application context
  • Timestamp

Performance Considerations​

Storage Optimization​

  • Efficient blob and table queries
  • Memory stream usage for large files
  • Async operations throughout

Caching Strategy​

  • No built-in caching (consider for frequently accessed data)
  • Client-side caching recommended for static data

Data Processing​

  • Optimized time series calculations
  • Efficient JSON/CSV parsing
  • Minimal memory footprint

Configuration​

Required Settings​

{
  "Values": {
    "CloudStorageConnectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net"
  },
  "Auth": {
    "ApiUser": {
      "Username": "api_user",
      "Password": "api_password"
    }
  },
  "Jwt": {
    "Issuer": "swmm_api",
    "Audience": "swmm_clients",
    "Key": "your_jwt_signing_key"
  },
  "Esri": {
    "ClientId": "your_esri_client_id",
    "ClientSecret": "your_esri_client_secret"
  }
}

Usage Examples​

Basic Authentication​

# Login
POST /api/auth/login
{
  "userName": "api_user",
  "password": "api_password"
}

# Use token in subsequent requests
Authorization: Bearer <jwt_token>

Get Network Data​

# Get all nodes
GET /api/node/nodes

# Get node time series
GET /api/node/values?index=0&runDateTime=2023-11-16T00:00:00-05:00&measurementIndex=0&scenario=scenario0

# Get all links
GET /api/link/links

# Get link time series
GET /api/link/values?index=0&runDateTime=2023-11-16T00:00:00-05:00&measurementIndex=0&scenario=scenario0

Scenario Management​

# Create scenario
POST /api/scenariomanagement
{
  "name": "Urban Stormwater",
  "description": "Urban area simulation",
  "inputFile": "urban.inp"
}

# Create run
POST /api/runmanagement
{
  "scenarioId": "scenario1",
  "startTime": "2023-11-16T00:00:00-05:00",
  "endTime": "2023-11-16T23:59:59-05:00",
  "reportingTimeStep": 15
}

Sensor Data​

# Get sensor value
GET /api/sensor/nodevalues?sensorId=SENSOR001&measurement=depth&reportingDateTime=2023-11-16T12:00:00-05:00&reportingTimeStep=15

# Get sensor time series
GET /api/sensor/linktimeseries?sensorId=SENSOR002&measurement=flow&startTime=2023-11-16T00:00:00-05:00&endTime=2023-11-16T23:59:59-05:00&reportingTimeStep=15

Dependencies​

Core Dependencies​

  • Azure.Storage.Blobs
  • Azure.Data.Tables
  • Microsoft.AspNetCore.Mvc
  • System.Text.Json

Internal Dependencies​

  • GqcStorage1: Storage utilities
  • SwmmModels: Data models
  • SwmmUtilities: Time series processing

Monitoring & Logging​

Application Logging​

  • Request/response logging
  • Performance metrics
  • Error tracking
  • Audit trails

Storage Monitoring​

  • Blob access patterns
  • Table query performance
  • Storage capacity usage
  • Error rates

Future Enhancements​

  1. Caching Layer: Implement Redis or in-memory caching
  2. Real-time Updates: WebSocket support for live data
  3. Advanced Filtering: Complex query capabilities
  4. Bulk Operations: Batch processing for large datasets
  5. API Versioning: Versioned API endpoints
  6. Rate Limiting: Request throttling
  7. Metrics Dashboard: Real-time API performance monitoring

Support & Maintenance​

Error Recovery​

  • Graceful handling of storage failures
  • Automatic retry mechanisms
  • Data validation and integrity checks

Performance Optimization​

  • Query optimization
  • Connection pooling
  • Memory management
  • Async operation patterns

Security Updates​

  • Regular dependency updates
  • Security patch management
  • Access control reviews
  • Audit log monitoring