API Reference
API Overview
Comprehensive API documentation for Flutter app and ESP32 communication
API Architecture
Gridova uses a hybrid architecture with REST API for standard operations and WebSocket for real-time sensor data streaming.
Base URLs
Backend API
// Production
https://api.gridova.com
// Development
http://localhost:8000
// Staging
https://staging-api.gridova.comESP32 Device API
// Device IP (configured per installation)
http://192.168.1.100
// Example endpoints
http://192.168.1.100/api/sensor
http://192.168.1.100/api/relayEach ESP32 device has its own IP address on the local network.
WebSocket URL
// Production
wss://api.gridova.com/ws
// Development
ws://localhost:8000/wsAuthentication
Gridova uses JWT (JSON Web Tokens) for authentication.
Login
Requestjson
POST /api/auth/login
{
"email": "admin@gridova.com",
"password": "admin123"
}Response (200 OK)json
{
"success": true,
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": {
"id": 1,
"email": "admin@gridova.com",
"name": "Admin User",
"role": "admin"
}
}Using the Token
// Include token in Authorization header
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...All protected endpoints require this header.
API Endpoints Overview
Backend API Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /api/auth/login | POST | Authenticate user |
| /api/rooms | GET | List all rooms |
| /api/rooms/:id | GET | Get room details |
| /api/tenants | GET | List all tenants |
| /api/transactions | GET | List transactions |
| /api/reports/energy | GET | Energy consumption report |
ESP32 Device Endpoints
| Endpoint | Method | Description |
|---|---|---|
| /api/sensor | GET | Get current sensor readings |
| /api/sensor/history | GET | Get historical data |
| /api/relay | GET | Get relay status |
| /api/relay/control | POST | Control relay (ON/OFF) |
| /api/status | GET | Device health check |
Response Format
All API responses follow a consistent JSON format:
Success Response
{
"success": true,
"data": {
// Response data
},
"message": "Operation completed successfully"
}Error Response
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input data",
"details": {
"field": "email",
"issue": "Invalid email format"
}
}
}HTTP Status Codes
| Code | Status | Description |
|---|---|---|
| 200 | OK | Request successful |
| 201 | Created | Resource created successfully |
| 400 | Bad Request | Invalid request data |
| 401 | Unauthorized | Authentication required |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource not found |
| 500 | Server Error | Internal server error |
Rate Limiting
API requests are rate limited to ensure fair usage:
- Backend API: 100 requests per minute per IP
- ESP32 Device: 10 requests per second
- WebSocket: 1 connection per device
Rate Limit Exceeded
When rate limit is exceeded, the API returns status code 429 (Too Many Requests). Implement exponential backoff in your client applications.