Phase 2 - API Interface

Building upon the standardized data formats established in Phase 1, Phase 2 of WIA-BEMS defines comprehensive API interfaces that enable applications to access, control, and manage building energy systems. These RESTful APIs eliminate the need for custom integration code, enable a competitive marketplace of applications, and provide the foundation for sophisticated energy management solutions.

This chapter explores the complete Phase 2 API specification, examining endpoint design, authentication mechanisms, real-time capabilities, and implementation best practices that ensure secure, performant, and reliable building energy management systems.

RESTful API Design Principles

WIA-BEMS Phase 2 APIs follow RESTful design principles that make them intuitive, consistent, and easy to implement across different programming languages and platforms.

Resource-Oriented Architecture

APIs are organized around resources (buildings, meters, sensors, equipment) rather than actions. Each resource has a unique URL and supports standard HTTP methods (GET, POST, PUT, DELETE) with consistent, predictable behavior.

Stateless Communication

Each API request contains all information necessary to process it. Servers don't maintain session state, enabling horizontal scaling and simplifying client implementation. Authentication tokens provide secure, stateless identity verification.

Standard HTTP Status Codes

APIs use standard HTTP status codes consistently: 200 for success, 201 for resource creation, 400 for client errors, 401 for authentication failures, 404 for not found, 500 for server errors. This consistency enables generic error handling in client applications.

HATEOAS and Discoverability

Responses include hypermedia links that guide clients to related resources and available actions. This makes APIs self-documenting and enables clients to navigate relationships without hardcoding URLs.

Core API Endpoints

Phase 2 defines comprehensive endpoints for all building energy management operations. Let's examine the key endpoint categories.

Building Management Endpoints

GET /api/v1/buildings?limit=50&offset=0&sort=name

Response: 200 OK
{
  "buildings": [
    {
      "building_id": "BLDG-001",
      "name": "Headquarters Tower",
      "address": {
        "street": "123 Energy Way",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102"
      },
      "area_sqm": 25000,
      "floors": 10,
      "type": "commercial_office",
      "year_built": 2018,
      "certifications": ["LEED Gold", "Energy Star"],
      "links": {
        "self": "/api/v1/buildings/BLDG-001",
        "meters": "/api/v1/buildings/BLDG-001/meters",
        "equipment": "/api/v1/buildings/BLDG-001/equipment",
        "energy": "/api/v1/buildings/BLDG-001/energy"
      }
    }
  ],
  "pagination": {
    "total": 125,
    "limit": 50,
    "offset": 0,
    "next": "/api/v1/buildings?limit=50&offset=50"
  }
}

Energy Data Endpoints

GET /api/v1/buildings/BLDG-001/energy?
    start=2025-01-01T00:00:00Z&
    end=2025-01-31T23:59:59Z&
    interval=1h&
    meter_id=METER-E-301

Response: 200 OK
{
  "building_id": "BLDG-001",
  "query": {
    "start": "2025-01-01T00:00:00Z",
    "end": "2025-01-31T23:59:59Z",
    "interval": "1h",
    "meter_id": "METER-E-301"
  },
  "data": [
    {
      "timestamp_start": "2025-01-01T00:00:00Z",
      "timestamp_end": "2025-01-01T01:00:00Z",
      "energy_kwh": 125.5,
      "cost_usd": 18.75,
      "quality": "verified"
    },
    {
      "timestamp_start": "2025-01-01T01:00:00Z",
      "timestamp_end": "2025-01-01T02:00:00Z",
      "energy_kwh": 118.2,
      "cost_usd": 17.73,
      "quality": "verified"
    }
  ],
  "summary": {
    "total_energy_kwh": 95240.5,
    "total_cost_usd": 14286.08,
    "avg_power_kw": 128.0,
    "peak_power_kw": 205.3,
    "data_completeness": 99.8
  }
}

Query Parameter	Type	Description	Example
start	ISO 8601 timestamp	Start of query period	2025-01-01T00:00:00Z
end	ISO 8601 timestamp	End of query period	2025-01-31T23:59:59Z
interval	Duration string	Aggregation interval	15m, 1h, 1d
meter_id	String	Filter by specific meter	METER-E-301
floor	Integer	Filter by floor	3
zone	String	Filter by zone	East-Wing

Real-time Data Streaming

// WebSocket connection
ws://api.example.com/api/v1/buildings/BLDG-001/realtime

// Subscribe to data streams
{
  "action": "subscribe",
  "streams": [
    {
      "type": "power_demand",
      "meter_id": "METER-E-301",
      "sample_rate": "1s"
    },
    {
      "type": "temperature",
      "zone": "Conference-Room-A",
      "sample_rate": "30s"
    }
  ]
}

// Receive real-time updates
{
  "stream_id": "power_demand_METER-E-301",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "data": {
    "power_kw": 150.25,
    "voltage_v": 480,
    "current_a": 320,
    "power_factor": 0.92
  }
}

Equipment Control Endpoints

POST /api/v1/buildings/BLDG-001/equipment/AHU-301/commands

{
  "command": "set_temperature",
  "parameters": {
    "supply_air_temp_setpoint_c": 14.0
  },
  "authorization": {
    "override_reason": "Optimization test",
    "duration_minutes": 60
  }
}

Response: 202 Accepted
{
  "command_id": "cmd-12345",
  "status": "accepted",
  "equipment_id": "AHU-301",
  "estimated_completion": "2025-01-15T14:30:15Z",
  "links": {
    "status": "/api/v1/commands/cmd-12345"
  }
}

Analytics and Optimization Endpoints

POST /api/v1/buildings/BLDG-001/analytics

{
  "analysis_type": "energy_optimization",
  "parameters": {
    "target_metric": "cost_reduction",
    "constraint": "maintain_comfort",
    "horizon_hours": 24
  }
}

Response: 200 OK
{
  "analysis_id": "ana-67890",
  "recommendations": [
    {
      "action": "adjust_hvac_schedule",
      "equipment_id": "AHU-301",
      "current_setting": "24/7 operation",
      "recommended_setting": "7am-7pm weekdays only",
      "projected_savings_kwh": 450,
      "projected_savings_usd": 67.50,
      "confidence": 0.87
    },
    {
      "action": "reduce_lighting_levels",
      "zone": "Open-Office-East",
      "current_setting": "100% brightness",
      "recommended_setting": "75% brightness",
      "projected_savings_kwh": 125,
      "projected_savings_usd": 18.75,
      "confidence": 0.95
    }
  ],
  "summary": {
    "total_savings_kwh": 575,
    "total_savings_usd": 86.25,
    "payback_period_days": 0,
    "risk_level": "low"
  }
}

Authentication and Authorization

Security is paramount in building energy management APIs. Phase 2 specifies comprehensive authentication and authorization mechanisms.

OAuth 2.0 Authentication

WIA-BEMS uses OAuth 2.0 for authentication, supporting multiple grant types for different use cases.

// Authorization Code Flow (for user applications)
POST /oauth/token

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE_FROM_AUTHORIZATION_ENDPOINT",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://yourapp.com/callback"
}

Response: 200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
  "scope": "building:read energy:read equipment:control"
}

// Client Credentials Flow (for service accounts)
POST /oauth/token

{
  "grant_type": "client_credentials",
  "client_id": "service_account_id",
  "client_secret": "service_account_secret",
  "scope": "building:read energy:read"
}

// Use token in API requests
GET /api/v1/buildings/BLDG-001/energy
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Role-Based Access Control

Fine-grained permissions control what users and applications can access and modify.

Role	Permissions	Typical Use Case
Viewer	Read building data, energy consumption	Dashboard displays, reporting tools
Operator	Viewer + send commands, adjust setpoints	Building operators, facility managers
Administrator	Operator + configure devices, manage users	System administrators, integrators
Energy Manager	Viewer + analytics, optimization requests	Energy consultants, analysts
Service Account	Configurable per application	Automated systems, integrations

Error Handling and Response Codes

Comprehensive error handling ensures applications can gracefully handle failures and provide useful feedback to users.

Standard Error Response Format

// Example error response
Response: 400 Bad Request
{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'interval' parameter must be one of: 1m, 5m, 15m, 1h, 1d",
    "details": {
      "parameter": "interval",
      "provided_value": "2h",
      "allowed_values": ["1m", "5m", "15m", "1h", "1d"]
    },
    "timestamp": "2025-01-15T14:30:00Z",
    "request_id": "req-abc123"
  }
}

HTTP Code	Error Code	Description	Client Action
400	INVALID_PARAMETER	Request parameter is invalid	Fix parameter and retry
401	UNAUTHORIZED	Authentication required or failed	Obtain valid token
403	FORBIDDEN	Insufficient permissions	Request access or use different account
404	RESOURCE_NOT_FOUND	Requested resource doesn't exist	Verify resource ID
429	RATE_LIMIT_EXCEEDED	Too many requests	Wait and retry (check Retry-After header)
503	SERVICE_UNAVAILABLE	Temporary service outage	Retry with exponential backoff

Pagination and Performance

APIs must handle large datasets efficiently without overwhelming clients or servers.

Cursor-Based Pagination

GET /api/v1/buildings/BLDG-001/energy?
    start=2025-01-01T00:00:00Z&
    end=2025-12-31T23:59:59Z&
    limit=1000

Response: 200 OK
{
  "data": [...], // 1000 records
  "pagination": {
    "next_cursor": "eyJsYXN0X2lkIjo...",
    "has_more": true
  },
  "links": {
    "next": "/api/v1/buildings/BLDG-001/energy?cursor=eyJsYXN0X2lkIjo..."
  }
}

Rate Limiting

APIs implement rate limiting to ensure fair resource allocation and prevent abuse.

// Rate limit headers in response
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1642267200

// When rate limit exceeded
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit of 1000 requests per hour exceeded",
    "retry_after_seconds": 60
  }
}

Versioning Strategy

APIs evolve over time. WIA-BEMS uses URL-based versioning to maintain backwards compatibility.

// Version 1 API
GET /api/v1/buildings/BLDG-001/energy

// Future version 2 API (with breaking changes)
GET /api/v2/buildings/BLDG-001/energy

// Version specified in Accept header (alternative)
GET /api/buildings/BLDG-001/energy
Accept: application/vnd.wia.bems.v1+json

Deprecation Policy

• Major versions supported for minimum 2 years after successor release
• Deprecated endpoints return warning headers 6 months before removal
• Breaking changes only introduced in new major versions
• Non-breaking enhancements added to current version

Implementation Best Practices

Successfully implementing Phase 2 APIs requires attention to several key considerations.

Client-Side Best Practices

• Handle rate limits gracefully: Implement exponential backoff and respect Retry-After headers
• Cache responses appropriately: Use ETag and If-None-Match headers to reduce bandwidth
• Implement robust error handling: Don't assume all requests succeed; handle all error codes
• Use connection pooling: Reuse HTTP connections to reduce latency and overhead
• Validate responses: Check data against schemas before using in application logic
• Secure token storage: Never expose tokens in URLs, logs, or client-side code

Server-Side Best Practices

• Implement comprehensive logging: Log all API requests with request IDs for debugging
• Use database indexing: Index frequently queried fields (timestamp, building_id, etc.)
• Implement query optimization: Use appropriate database queries and avoid N+1 problems
• Enable compression: Use gzip or brotli compression to reduce bandwidth
• Monitor performance: Track response times, error rates, and resource utilization
• Implement circuit breakers: Protect against cascading failures in distributed systems