1749 lines
45 KiB
YAML
1749 lines
45 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Energy Management API
|
|
description: |
|
|
Central API gateway for energy management microservices.
|
|
|
|
This API provides comprehensive energy management functionality including:
|
|
- Token-based authentication and authorization
|
|
- Sensor and room monitoring
|
|
- Battery management and optimization
|
|
- Demand response event management
|
|
- Real-time data ingestion and analytics
|
|
- Data export and reporting
|
|
|
|
All requests are routed through the API Gateway running on port 8000.
|
|
version: 1.0.0
|
|
contact:
|
|
name: API Support
|
|
email: support@example.com
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
|
|
servers:
|
|
- url: http://localhost:8000
|
|
description: Local development server
|
|
- url: http://localhost:8000/api/v1
|
|
description: API Gateway v1
|
|
|
|
tags:
|
|
- name: Gateway
|
|
description: API Gateway health and statistics
|
|
- name: Authentication
|
|
description: Token management and authentication
|
|
- name: Sensors
|
|
description: Sensor management and data retrieval
|
|
- name: Rooms
|
|
description: Room management and monitoring
|
|
- name: Analytics
|
|
description: Data analytics and reporting
|
|
- name: Demand Response
|
|
description: Demand response event management
|
|
- name: Batteries
|
|
description: Battery monitoring and control
|
|
- name: Data Ingestion
|
|
description: Data ingestion and source management
|
|
|
|
security:
|
|
- BearerAuth: []
|
|
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: JWT token obtained from /api/v1/tokens/generate
|
|
|
|
schemas:
|
|
HealthResponse:
|
|
type: object
|
|
properties:
|
|
service:
|
|
type: string
|
|
example: api-gateway
|
|
status:
|
|
type: string
|
|
enum: [healthy, degraded, unhealthy]
|
|
example: healthy
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
version:
|
|
type: string
|
|
example: 1.0.0
|
|
services:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
healthy_services:
|
|
type: integer
|
|
total_services:
|
|
type: integer
|
|
|
|
GatewayStats:
|
|
type: object
|
|
properties:
|
|
total_requests:
|
|
type: integer
|
|
example: 1523
|
|
successful_requests:
|
|
type: integer
|
|
example: 1498
|
|
failed_requests:
|
|
type: integer
|
|
example: 25
|
|
success_rate:
|
|
type: number
|
|
format: float
|
|
example: 98.36
|
|
uptime_seconds:
|
|
type: number
|
|
format: float
|
|
example: 3600.5
|
|
service_requests:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
|
|
TokenGenerateRequest:
|
|
type: object
|
|
required:
|
|
- name
|
|
- list_of_resources
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Token name or identifier
|
|
example: dashboard-token
|
|
list_of_resources:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of resources this token can access
|
|
example: [sensor_1, sensor_2, room_A]
|
|
data_aggregation:
|
|
type: boolean
|
|
default: false
|
|
description: Allow data aggregation
|
|
time_aggregation:
|
|
type: boolean
|
|
default: false
|
|
description: Allow time-based aggregation
|
|
embargo:
|
|
type: boolean
|
|
default: false
|
|
description: Apply embargo restrictions
|
|
exp_hours:
|
|
type: integer
|
|
default: 24
|
|
description: Token expiration in hours
|
|
example: 24
|
|
|
|
TokenResponse:
|
|
type: object
|
|
properties:
|
|
token:
|
|
type: string
|
|
description: JWT token string
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
|
|
TokenValidationResponse:
|
|
type: object
|
|
properties:
|
|
valid:
|
|
type: boolean
|
|
example: true
|
|
token:
|
|
type: string
|
|
decoded:
|
|
type: object
|
|
nullable: true
|
|
error:
|
|
type: string
|
|
nullable: true
|
|
|
|
SensorMetadata:
|
|
type: object
|
|
required:
|
|
- sensor_id
|
|
- sensor_type
|
|
properties:
|
|
sensor_id:
|
|
type: string
|
|
example: sensor_1
|
|
sensor_type:
|
|
type: string
|
|
enum: [temperature, humidity, co2, energy, occupancy]
|
|
room:
|
|
type: string
|
|
example: Room A
|
|
location:
|
|
type: string
|
|
example: Northeast corner
|
|
status:
|
|
type: string
|
|
enum: [active, inactive, maintenance, error]
|
|
default: active
|
|
metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
SensorReading:
|
|
type: object
|
|
required:
|
|
- sensor_id
|
|
- timestamp
|
|
- value
|
|
properties:
|
|
sensor_id:
|
|
type: string
|
|
example: sensor_1
|
|
timestamp:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp
|
|
example: 1702396800
|
|
value:
|
|
type: number
|
|
format: float
|
|
example: 23.5
|
|
unit:
|
|
type: string
|
|
example: celsius
|
|
room:
|
|
type: string
|
|
example: Room A
|
|
|
|
RoomCreate:
|
|
type: object
|
|
required:
|
|
- name
|
|
properties:
|
|
name:
|
|
type: string
|
|
example: Conference Room A
|
|
description:
|
|
type: string
|
|
example: Main conference room on first floor
|
|
floor:
|
|
type: integer
|
|
example: 1
|
|
area_sqm:
|
|
type: number
|
|
format: float
|
|
example: 45.5
|
|
capacity:
|
|
type: integer
|
|
example: 12
|
|
room_type:
|
|
type: string
|
|
example: conference
|
|
|
|
RoomUpdate:
|
|
type: object
|
|
properties:
|
|
description:
|
|
type: string
|
|
floor:
|
|
type: integer
|
|
area_sqm:
|
|
type: number
|
|
format: float
|
|
capacity:
|
|
type: integer
|
|
room_type:
|
|
type: string
|
|
|
|
DataQuery:
|
|
type: object
|
|
properties:
|
|
sensor_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example: [sensor_1, sensor_2]
|
|
start_time:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp
|
|
end_time:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp
|
|
limit:
|
|
type: integer
|
|
default: 100
|
|
example: 100
|
|
offset:
|
|
type: integer
|
|
default: 0
|
|
example: 0
|
|
|
|
EventRequest:
|
|
type: object
|
|
required:
|
|
- event_time
|
|
- load_kwh
|
|
- load_percentage
|
|
- iots
|
|
properties:
|
|
event_time:
|
|
type: string
|
|
format: date-time
|
|
description: When the DR event should occur
|
|
example: 2025-12-10T14:00:00
|
|
load_kwh:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
exclusiveMinimum: true
|
|
description: Target load reduction in kWh
|
|
example: 5.0
|
|
load_percentage:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
maximum: 100
|
|
description: Target reduction as percentage of total load
|
|
example: 15.0
|
|
iots:
|
|
type: array
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
description: List of device IDs to participate
|
|
example: [sensor_1, sensor_2]
|
|
duration_minutes:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 120
|
|
default: 59
|
|
description: Event duration in minutes
|
|
example: 59
|
|
|
|
InvitationResponse:
|
|
type: object
|
|
required:
|
|
- event_id
|
|
- iot_id
|
|
- response
|
|
properties:
|
|
event_id:
|
|
type: string
|
|
example: 550e8400-e29b-41d4-a716-446655440000
|
|
iot_id:
|
|
type: string
|
|
example: sensor_1
|
|
response:
|
|
type: string
|
|
enum: [WAITING, YES, NO]
|
|
example: YES
|
|
committed_reduction_kw:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
nullable: true
|
|
example: 2.5
|
|
|
|
LoadReductionRequest:
|
|
type: object
|
|
required:
|
|
- target_reduction_kw
|
|
- duration_minutes
|
|
properties:
|
|
target_reduction_kw:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
exclusiveMinimum: true
|
|
example: 5.0
|
|
duration_minutes:
|
|
type: integer
|
|
minimum: 1
|
|
example: 60
|
|
priority_iots:
|
|
type: array
|
|
items:
|
|
type: string
|
|
nullable: true
|
|
example: [sensor_1, sensor_2]
|
|
|
|
FlexibilityResponse:
|
|
type: object
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
total_flexibility_kw:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
example: 15.5
|
|
devices:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
device_id:
|
|
type: string
|
|
example: sensor_1
|
|
available_kw:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
example: 3.5
|
|
instruction:
|
|
type: string
|
|
example: participation
|
|
current_power:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
example: 3.5
|
|
|
|
BatteryStatus:
|
|
type: object
|
|
properties:
|
|
battery_id:
|
|
type: string
|
|
example: battery_1
|
|
capacity:
|
|
type: number
|
|
format: float
|
|
description: Total battery capacity in kWh
|
|
example: 13.5
|
|
stored_energy:
|
|
type: number
|
|
format: float
|
|
description: Current stored energy in kWh
|
|
example: 10.8
|
|
state_of_charge:
|
|
type: number
|
|
format: float
|
|
description: State of charge percentage (0-100)
|
|
example: 80.0
|
|
status:
|
|
type: string
|
|
enum: [charging, discharging, idle, maintenance]
|
|
example: idle
|
|
power_kw:
|
|
type: number
|
|
format: float
|
|
description: Current power flow in kW (positive = charging)
|
|
example: 0.0
|
|
last_updated:
|
|
type: string
|
|
format: date-time
|
|
|
|
ChargingRequest:
|
|
type: object
|
|
required:
|
|
- power_kw
|
|
- duration_minutes
|
|
properties:
|
|
power_kw:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
exclusiveMinimum: true
|
|
example: 3.5
|
|
duration_minutes:
|
|
type: integer
|
|
minimum: 1
|
|
example: 60
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
detail:
|
|
type: string
|
|
example: Resource not found
|
|
status_code:
|
|
type: integer
|
|
example: 404
|
|
|
|
paths:
|
|
# Gateway Endpoints
|
|
/health:
|
|
get:
|
|
tags:
|
|
- Gateway
|
|
summary: Gateway health check
|
|
description: Check the health status of the API Gateway and all registered microservices
|
|
operationId: getGatewayHealth
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Health check successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HealthResponse'
|
|
'503':
|
|
description: Service unavailable
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/services/status:
|
|
get:
|
|
tags:
|
|
- Gateway
|
|
summary: Get services status
|
|
description: Get detailed status of all registered microservices
|
|
operationId: getServicesStatus
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Services status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
services:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
total_services:
|
|
type: integer
|
|
healthy_services:
|
|
type: integer
|
|
|
|
/stats:
|
|
get:
|
|
tags:
|
|
- Gateway
|
|
summary: Get gateway statistics
|
|
description: Get API Gateway request statistics and performance metrics
|
|
operationId: getGatewayStats
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Statistics retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GatewayStats'
|
|
|
|
/api/v1/overview:
|
|
get:
|
|
tags:
|
|
- Gateway
|
|
summary: Get system overview
|
|
description: Get comprehensive overview from all services
|
|
operationId: getSystemOverview
|
|
responses:
|
|
'200':
|
|
description: System overview retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
system_overview:
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
services_checked:
|
|
type: integer
|
|
|
|
# Token Service Endpoints
|
|
/api/v1/tokens/generate:
|
|
post:
|
|
tags:
|
|
- Authentication
|
|
summary: Generate new JWT token
|
|
description: Generate a new JWT token with specified permissions and resources
|
|
operationId: generateToken
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TokenGenerateRequest'
|
|
responses:
|
|
'200':
|
|
description: Token generated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TokenResponse'
|
|
'500':
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/v1/tokens/validate:
|
|
post:
|
|
tags:
|
|
- Authentication
|
|
summary: Validate JWT token
|
|
description: Validate and decode a JWT token
|
|
operationId: validateToken
|
|
security: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- token
|
|
properties:
|
|
token:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Token validation result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TokenValidationResponse'
|
|
|
|
/api/v1/tokens:
|
|
get:
|
|
tags:
|
|
- Authentication
|
|
summary: Get all tokens
|
|
description: Retrieve list of all tokens
|
|
operationId: getTokens
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Tokens retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
tokens:
|
|
type: array
|
|
items:
|
|
type: object
|
|
count:
|
|
type: integer
|
|
|
|
# Sensor Service Endpoints
|
|
/api/v1/sensors/get:
|
|
get:
|
|
tags:
|
|
- Sensors
|
|
summary: Get all sensors
|
|
description: Get all sensors with optional filtering by room, type, or status
|
|
operationId: getSensors
|
|
parameters:
|
|
- name: room
|
|
in: query
|
|
description: Filter by room name
|
|
schema:
|
|
type: string
|
|
- name: sensor_type
|
|
in: query
|
|
description: Filter by sensor type
|
|
schema:
|
|
type: string
|
|
enum: [temperature, humidity, co2, energy, occupancy]
|
|
- name: status
|
|
in: query
|
|
description: Filter by sensor status
|
|
schema:
|
|
type: string
|
|
enum: [active, inactive, maintenance, error]
|
|
responses:
|
|
'200':
|
|
description: Sensors retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
sensors:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SensorMetadata'
|
|
count:
|
|
type: integer
|
|
filters:
|
|
type: object
|
|
|
|
/api/v1/sensors/{sensor_id}:
|
|
get:
|
|
tags:
|
|
- Sensors
|
|
summary: Get sensor details
|
|
description: Get detailed information about a specific sensor
|
|
operationId: getSensorDetails
|
|
parameters:
|
|
- name: sensor_id
|
|
in: path
|
|
required: true
|
|
description: Sensor identifier
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Sensor details retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SensorMetadata'
|
|
'404':
|
|
description: Sensor not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
put:
|
|
tags:
|
|
- Sensors
|
|
summary: Update sensor
|
|
description: Update sensor metadata
|
|
operationId: updateSensor
|
|
parameters:
|
|
- name: sensor_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
responses:
|
|
'200':
|
|
description: Sensor updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
sensor_id:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
delete:
|
|
tags:
|
|
- Sensors
|
|
summary: Delete sensor
|
|
description: Delete a sensor and all its data
|
|
operationId: deleteSensor
|
|
parameters:
|
|
- name: sensor_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Sensor deleted successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
sensor_id:
|
|
type: string
|
|
readings_deleted:
|
|
type: integer
|
|
|
|
/api/v1/sensors:
|
|
post:
|
|
tags:
|
|
- Sensors
|
|
summary: Create sensor
|
|
description: Register a new sensor
|
|
operationId: createSensor
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SensorMetadata'
|
|
responses:
|
|
'200':
|
|
description: Sensor created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
sensor_id:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
'400':
|
|
description: Invalid request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/v1/sensors/{sensor_id}/data:
|
|
get:
|
|
tags:
|
|
- Sensors
|
|
summary: Get sensor data
|
|
description: Get historical data for a specific sensor
|
|
operationId: getSensorData
|
|
parameters:
|
|
- name: sensor_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: start_time
|
|
in: query
|
|
description: Start timestamp (Unix)
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
- name: end_time
|
|
in: query
|
|
description: End timestamp (Unix)
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
- name: limit
|
|
in: query
|
|
description: Maximum records to return
|
|
schema:
|
|
type: integer
|
|
default: 100
|
|
- name: offset
|
|
in: query
|
|
description: Records to skip
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
responses:
|
|
'200':
|
|
description: Sensor data retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
data:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SensorReading'
|
|
total_count:
|
|
type: integer
|
|
query:
|
|
$ref: '#/components/schemas/DataQuery'
|
|
execution_time_ms:
|
|
type: number
|
|
|
|
# Room Management Endpoints
|
|
/api/v1/rooms/names:
|
|
get:
|
|
tags:
|
|
- Rooms
|
|
summary: Get room names
|
|
description: Get simple list of room names for dropdowns
|
|
operationId: getRoomNames
|
|
responses:
|
|
'200':
|
|
description: Room names retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
rooms:
|
|
type: array
|
|
items:
|
|
type: string
|
|
count:
|
|
type: integer
|
|
|
|
/api/v1/rooms:
|
|
get:
|
|
tags:
|
|
- Rooms
|
|
summary: Get all rooms
|
|
description: Get all rooms with sensor counts and metrics
|
|
operationId: getRooms
|
|
responses:
|
|
'200':
|
|
description: Rooms retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
rooms:
|
|
type: array
|
|
items:
|
|
type: object
|
|
count:
|
|
type: integer
|
|
|
|
post:
|
|
tags:
|
|
- Rooms
|
|
summary: Create room
|
|
description: Create a new room
|
|
operationId: createRoom
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RoomCreate'
|
|
responses:
|
|
'200':
|
|
description: Room created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
room:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
'400':
|
|
description: Invalid request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/v1/rooms/{room_name}:
|
|
get:
|
|
tags:
|
|
- Rooms
|
|
summary: Get room details
|
|
description: Get detailed room information
|
|
operationId: getRoomDetails
|
|
parameters:
|
|
- name: room_name
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Room details retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
'404':
|
|
description: Room not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
put:
|
|
tags:
|
|
- Rooms
|
|
summary: Update room
|
|
description: Update an existing room
|
|
operationId: updateRoom
|
|
parameters:
|
|
- name: room_name
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RoomUpdate'
|
|
responses:
|
|
'200':
|
|
description: Room updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
room:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
modified:
|
|
type: boolean
|
|
|
|
delete:
|
|
tags:
|
|
- Rooms
|
|
summary: Delete room
|
|
description: Delete a room
|
|
operationId: deleteRoom
|
|
parameters:
|
|
- name: room_name
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Room deleted successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
|
|
/api/v1/rooms/{room_name}/data:
|
|
get:
|
|
tags:
|
|
- Rooms
|
|
summary: Get room data
|
|
description: Get historical data for a specific room
|
|
operationId: getRoomData
|
|
parameters:
|
|
- name: room_name
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: start_time
|
|
in: query
|
|
description: Start timestamp (Unix)
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
- name: end_time
|
|
in: query
|
|
description: End timestamp (Unix)
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
- name: limit
|
|
in: query
|
|
description: Maximum records to return
|
|
schema:
|
|
type: integer
|
|
default: 100
|
|
responses:
|
|
'200':
|
|
description: Room data retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
room:
|
|
type: string
|
|
room_metrics:
|
|
type: array
|
|
items:
|
|
type: object
|
|
sensor_readings:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SensorReading'
|
|
period:
|
|
type: object
|
|
properties:
|
|
start_time:
|
|
type: integer
|
|
end_time:
|
|
type: integer
|
|
|
|
# Analytics Endpoints
|
|
/api/v1/data/query:
|
|
post:
|
|
tags:
|
|
- Analytics
|
|
summary: Query data
|
|
description: Advanced data querying with multiple filters
|
|
operationId: queryData
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DataQuery'
|
|
responses:
|
|
'200':
|
|
description: Query executed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
|
|
/api/v1/analytics/summary:
|
|
get:
|
|
tags:
|
|
- Analytics
|
|
summary: Get analytics summary
|
|
description: Get comprehensive analytics summary
|
|
operationId: getAnalyticsSummary
|
|
parameters:
|
|
- name: hours
|
|
in: query
|
|
description: Hours of data to analyze
|
|
schema:
|
|
type: integer
|
|
default: 24
|
|
responses:
|
|
'200':
|
|
description: Analytics summary retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
|
|
/api/v1/analytics/energy:
|
|
get:
|
|
tags:
|
|
- Analytics
|
|
summary: Get energy analytics
|
|
description: Get energy-specific analytics
|
|
operationId: getEnergyAnalytics
|
|
parameters:
|
|
- name: hours
|
|
in: query
|
|
description: Hours of data to analyze
|
|
schema:
|
|
type: integer
|
|
default: 24
|
|
- name: room
|
|
in: query
|
|
description: Filter by room
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Energy analytics retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
|
|
/api/v1/export:
|
|
get:
|
|
tags:
|
|
- Analytics
|
|
summary: Export data
|
|
description: Export sensor data in JSON or CSV format
|
|
operationId: exportData
|
|
parameters:
|
|
- name: start_time
|
|
in: query
|
|
required: true
|
|
description: Start timestamp (Unix)
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
- name: end_time
|
|
in: query
|
|
required: true
|
|
description: End timestamp (Unix)
|
|
schema:
|
|
type: integer
|
|
format: int64
|
|
- name: sensor_ids
|
|
in: query
|
|
description: Comma-separated sensor IDs
|
|
schema:
|
|
type: string
|
|
- name: format
|
|
in: query
|
|
description: Export format
|
|
schema:
|
|
type: string
|
|
enum: [json, csv]
|
|
default: json
|
|
responses:
|
|
'200':
|
|
description: Data exported successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
|
|
/api/v1/events:
|
|
get:
|
|
tags:
|
|
- Analytics
|
|
summary: Get system events
|
|
description: Get system events and alerts
|
|
operationId: getSystemEvents
|
|
parameters:
|
|
- name: severity
|
|
in: query
|
|
description: Filter by severity
|
|
schema:
|
|
type: string
|
|
- name: event_type
|
|
in: query
|
|
description: Filter by event type
|
|
schema:
|
|
type: string
|
|
- name: hours
|
|
in: query
|
|
description: Hours of events to retrieve
|
|
schema:
|
|
type: integer
|
|
default: 24
|
|
- name: limit
|
|
in: query
|
|
description: Maximum events to return
|
|
schema:
|
|
type: integer
|
|
default: 50
|
|
responses:
|
|
'200':
|
|
description: Events retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
events:
|
|
type: array
|
|
items:
|
|
type: object
|
|
count:
|
|
type: integer
|
|
period_hours:
|
|
type: integer
|
|
|
|
# Demand Response Endpoints
|
|
/api/v1/demand-response/invitations/send:
|
|
post:
|
|
tags:
|
|
- Demand Response
|
|
summary: Send demand response invitation
|
|
description: Send demand response invitation to specified IoT devices
|
|
operationId: sendDRInvitation
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/EventRequest'
|
|
responses:
|
|
'200':
|
|
description: Invitation sent successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
event_id:
|
|
type: string
|
|
event_time:
|
|
type: string
|
|
format: date-time
|
|
participants:
|
|
type: integer
|
|
load_kwh:
|
|
type: number
|
|
load_percentage:
|
|
type: number
|
|
|
|
/api/v1/demand-response/invitations/unanswered:
|
|
get:
|
|
tags:
|
|
- Demand Response
|
|
summary: Get unanswered invitations
|
|
description: Get all unanswered demand response invitations
|
|
operationId: getUnansweredInvitations
|
|
responses:
|
|
'200':
|
|
description: Unanswered invitations retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
invitations:
|
|
type: array
|
|
items:
|
|
type: object
|
|
count:
|
|
type: integer
|
|
|
|
/api/v1/demand-response/invitations/answered:
|
|
get:
|
|
tags:
|
|
- Demand Response
|
|
summary: Get answered invitations
|
|
description: Get answered demand response invitations
|
|
operationId: getAnsweredInvitations
|
|
parameters:
|
|
- name: hours
|
|
in: query
|
|
description: Hours to look back
|
|
schema:
|
|
type: integer
|
|
default: 24
|
|
responses:
|
|
'200':
|
|
description: Answered invitations retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
invitations:
|
|
type: array
|
|
items:
|
|
type: object
|
|
count:
|
|
type: integer
|
|
period_hours:
|
|
type: integer
|
|
|
|
/api/v1/demand-response/invitations/answer:
|
|
post:
|
|
tags:
|
|
- Demand Response
|
|
summary: Answer invitation
|
|
description: Answer a demand response invitation
|
|
operationId: answerDRInvitation
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/InvitationResponse'
|
|
responses:
|
|
'200':
|
|
description: Response recorded successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
event_id:
|
|
type: string
|
|
iot_id:
|
|
type: string
|
|
response:
|
|
type: string
|
|
committed_reduction:
|
|
type: number
|
|
'400':
|
|
description: Invalid request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/v1/demand-response/invitations/{event_id}:
|
|
get:
|
|
tags:
|
|
- Demand Response
|
|
summary: Get invitation details
|
|
description: Get details of a specific demand response invitation
|
|
operationId: getDRInvitation
|
|
parameters:
|
|
- name: event_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Invitation details retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
'404':
|
|
description: Invitation not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/v1/demand-response/events/active:
|
|
get:
|
|
tags:
|
|
- Demand Response
|
|
summary: Get active events
|
|
description: Get currently active demand response events
|
|
operationId: getActiveDREvents
|
|
responses:
|
|
'200':
|
|
description: Active events retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
events:
|
|
type: array
|
|
items:
|
|
type: object
|
|
count:
|
|
type: integer
|
|
|
|
/api/v1/demand-response/flexibility/current:
|
|
get:
|
|
tags:
|
|
- Demand Response
|
|
summary: Get current flexibility
|
|
description: Get current system flexibility capacity
|
|
operationId: getCurrentFlexibility
|
|
responses:
|
|
'200':
|
|
description: Flexibility retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
flexibility:
|
|
$ref: '#/components/schemas/FlexibilityResponse'
|
|
|
|
/api/v1/demand-response/flexibility/forecast:
|
|
get:
|
|
tags:
|
|
- Demand Response
|
|
summary: Get flexibility forecast
|
|
description: Get forecasted flexibility for the next specified hours
|
|
operationId: getFlexibilityForecast
|
|
parameters:
|
|
- name: hours
|
|
in: query
|
|
description: Forecast horizon in hours
|
|
schema:
|
|
type: integer
|
|
default: 24
|
|
responses:
|
|
'200':
|
|
description: Forecast retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
forecast_hours:
|
|
type: integer
|
|
flexibility_forecast:
|
|
type: object
|
|
generated_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
/api/v1/demand-response/load-reduction/execute:
|
|
post:
|
|
tags:
|
|
- Demand Response
|
|
summary: Execute load reduction
|
|
description: Execute immediate load reduction
|
|
operationId: executeLoadReduction
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LoadReductionRequest'
|
|
responses:
|
|
'200':
|
|
description: Load reduction executed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
target_reduction_kw:
|
|
type: number
|
|
actual_reduction_kw:
|
|
type: number
|
|
participating_devices:
|
|
type: array
|
|
items:
|
|
type: string
|
|
execution_time:
|
|
type: string
|
|
format: date-time
|
|
|
|
/api/v1/demand-response/analytics/performance:
|
|
get:
|
|
tags:
|
|
- Demand Response
|
|
summary: Get performance analytics
|
|
description: Get demand response performance analytics
|
|
operationId: getDRPerformanceAnalytics
|
|
parameters:
|
|
- name: days
|
|
in: query
|
|
description: Analysis period in days
|
|
schema:
|
|
type: integer
|
|
default: 30
|
|
responses:
|
|
'200':
|
|
description: Analytics retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
period_days:
|
|
type: integer
|
|
analytics:
|
|
type: object
|
|
generated_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
# Battery Endpoints
|
|
/api/v1/batteries:
|
|
get:
|
|
tags:
|
|
- Batteries
|
|
summary: Get all batteries
|
|
description: Get all registered batteries
|
|
operationId: getBatteries
|
|
responses:
|
|
'200':
|
|
description: Batteries retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
batteries:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/BatteryStatus'
|
|
count:
|
|
type: integer
|
|
total_capacity:
|
|
type: number
|
|
total_stored_energy:
|
|
type: number
|
|
|
|
/api/v1/batteries/{battery_id}:
|
|
get:
|
|
tags:
|
|
- Batteries
|
|
summary: Get battery status
|
|
description: Get specific battery status
|
|
operationId: getBatteryStatus
|
|
parameters:
|
|
- name: battery_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Battery status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
battery_id:
|
|
type: string
|
|
status:
|
|
$ref: '#/components/schemas/BatteryStatus'
|
|
'404':
|
|
description: Battery not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
/api/v1/batteries/{battery_id}/charge:
|
|
post:
|
|
tags:
|
|
- Batteries
|
|
summary: Charge battery
|
|
description: Charge a battery with specified power
|
|
operationId: chargeBattery
|
|
parameters:
|
|
- name: battery_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ChargingRequest'
|
|
responses:
|
|
'200':
|
|
description: Charging initiated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
battery_id:
|
|
type: string
|
|
power_kw:
|
|
type: number
|
|
duration_minutes:
|
|
type: integer
|
|
estimated_completion:
|
|
type: string
|
|
format: date-time
|
|
|
|
/api/v1/batteries/{battery_id}/discharge:
|
|
post:
|
|
tags:
|
|
- Batteries
|
|
summary: Discharge battery
|
|
description: Discharge a battery with specified power
|
|
operationId: dischargeBattery
|
|
parameters:
|
|
- name: battery_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ChargingRequest'
|
|
responses:
|
|
'200':
|
|
description: Discharging initiated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
battery_id:
|
|
type: string
|
|
power_kw:
|
|
type: number
|
|
duration_minutes:
|
|
type: integer
|
|
estimated_completion:
|
|
type: string
|
|
format: date-time
|
|
|
|
/api/v1/batteries/{battery_id}/history:
|
|
get:
|
|
tags:
|
|
- Batteries
|
|
summary: Get battery history
|
|
description: Get battery historical data
|
|
operationId: getBatteryHistory
|
|
parameters:
|
|
- name: battery_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: hours
|
|
in: query
|
|
description: Hours of history to retrieve
|
|
schema:
|
|
type: integer
|
|
default: 24
|
|
responses:
|
|
'200':
|
|
description: Battery history retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
battery_id:
|
|
type: string
|
|
period_hours:
|
|
type: integer
|
|
history:
|
|
type: array
|
|
items:
|
|
type: object
|
|
data_points:
|
|
type: integer
|
|
|
|
# Data Ingestion Endpoints
|
|
/api/v1/sources:
|
|
get:
|
|
tags:
|
|
- Data Ingestion
|
|
summary: Get data sources
|
|
description: Get all data ingestion sources
|
|
operationId: getDataSources
|
|
responses:
|
|
'200':
|
|
description: Data sources retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
sources:
|
|
type: array
|
|
items:
|
|
type: object
|
|
count:
|
|
type: integer
|
|
|
|
# WebSocket endpoint
|
|
/ws:
|
|
get:
|
|
tags:
|
|
- Sensors
|
|
summary: WebSocket connection
|
|
description: WebSocket endpoint for real-time sensor data streaming
|
|
operationId: websocketConnection
|
|
responses:
|
|
'101':
|
|
description: Switching Protocols - WebSocket connection established
|