Add versioned HTTP API routes
This commit is contained in:
+58
-50
@@ -8,6 +8,12 @@ Default AP address:
|
||||
http://192.168.4.1
|
||||
```
|
||||
|
||||
Current API base path:
|
||||
|
||||
```text
|
||||
/api/v1
|
||||
```
|
||||
|
||||
All documented endpoints are local-first and must continue to work without internet access. Consumers should ignore unknown response fields for forward compatibility.
|
||||
|
||||
Current firmware version:
|
||||
@@ -20,34 +26,36 @@ Current firmware version:
|
||||
|
||||
```text
|
||||
GET /
|
||||
GET /status
|
||||
GET /config
|
||||
GET /api/v1/status
|
||||
GET /api/v1/config
|
||||
|
||||
POST /relay/set
|
||||
POST /api/v1/relay/set
|
||||
|
||||
POST /config/device
|
||||
POST /config/relay
|
||||
POST /config/temp
|
||||
POST /config/bms
|
||||
POST /config/save
|
||||
POST /config/factory-reset
|
||||
POST /api/v1/config/device
|
||||
POST /api/v1/config/relay
|
||||
POST /api/v1/config/temp
|
||||
POST /api/v1/config/bms
|
||||
POST /api/v1/config/save
|
||||
POST /api/v1/config/factory-reset
|
||||
|
||||
GET /config/wifi
|
||||
POST /config/wifi
|
||||
POST /wifi/connect
|
||||
POST /wifi/clear
|
||||
GET /api/v1/config/wifi
|
||||
POST /api/v1/config/wifi
|
||||
POST /api/v1/wifi/connect
|
||||
POST /api/v1/wifi/clear
|
||||
|
||||
POST /temps/scan
|
||||
POST /temps/assign
|
||||
POST /temps/clear
|
||||
POST /api/v1/temps/scan
|
||||
POST /api/v1/temps/assign
|
||||
POST /api/v1/temps/clear
|
||||
|
||||
POST /bms/setup/enter
|
||||
POST /bms/setup/exit
|
||||
POST /bms/scan
|
||||
POST /bms/select
|
||||
POST /api/v1/bms/setup/enter
|
||||
POST /api/v1/bms/setup/exit
|
||||
POST /api/v1/bms/scan
|
||||
POST /api/v1/bms/select
|
||||
```
|
||||
|
||||
Legacy relay routes remain available:
|
||||
Pre-versioned root routes remain registered as compatibility aliases for existing local clients. New clients should use `/api/v1`.
|
||||
|
||||
Legacy GET relay routes remain available only as root compatibility aliases:
|
||||
|
||||
```text
|
||||
GET /relay/relay_1/on
|
||||
@@ -61,15 +69,15 @@ GET /relay/relay_2/off
|
||||
The Waveshare ESP32-S3 dashboard MVP should use only:
|
||||
|
||||
```text
|
||||
GET /status
|
||||
POST /relay/set
|
||||
GET /api/v1/status
|
||||
POST /api/v1/relay/set
|
||||
```
|
||||
|
||||
The dashboard is a client only. It may cache last-known values for display, but the Cargo ESP32 remains the source of truth for relay state, BMS state, alarms, and configuration.
|
||||
|
||||
## Status
|
||||
|
||||
### GET /status
|
||||
### GET /api/v1/status
|
||||
|
||||
Returns complete controller status.
|
||||
|
||||
@@ -144,7 +152,7 @@ Fields:
|
||||
| `online` | Current sensor detection state |
|
||||
| `temperature_f` | Current Fahrenheit value, or `null` when offline |
|
||||
|
||||
Config supports `temp_1` through `temp_8`. Current `/status` runtime output is limited to the configured count capped at four sensors.
|
||||
Config supports `temp_1` through `temp_8`. Current `/api/v1/status` runtime output is limited to the configured count capped at four sensors.
|
||||
|
||||
### relays
|
||||
|
||||
@@ -228,11 +236,11 @@ The AP remains enabled even when STA WiFi is configured or connected.
|
||||
|
||||
### config
|
||||
|
||||
`/status.config` embeds the same core configuration model used by `GET /config`.
|
||||
`/api/v1/status.config` embeds the same core configuration model used by `GET /api/v1/config`.
|
||||
|
||||
## Configuration
|
||||
|
||||
### GET /config
|
||||
### GET /api/v1/config
|
||||
|
||||
Returns saved controller configuration.
|
||||
|
||||
@@ -264,9 +272,9 @@ Returns saved controller configuration.
|
||||
}
|
||||
```
|
||||
|
||||
Note: current `GET /config` omits the `weather` field, while `/status.config.temperature_sensors[]` includes it.
|
||||
Note: current `GET /api/v1/config` omits the `weather` field, while `/api/v1/status.config.temperature_sensors[]` includes it.
|
||||
|
||||
### POST /config/device
|
||||
### POST /api/v1/config/device
|
||||
|
||||
Updates the controller display name.
|
||||
|
||||
@@ -278,7 +286,7 @@ Updates the controller display name.
|
||||
|
||||
Returns the updated config.
|
||||
|
||||
### POST /config/relay
|
||||
### POST /api/v1/config/relay
|
||||
|
||||
Updates relay configuration.
|
||||
|
||||
@@ -300,7 +308,7 @@ Fields:
|
||||
|
||||
Returns the updated config.
|
||||
|
||||
### POST /config/temp
|
||||
### POST /api/v1/config/temp
|
||||
|
||||
Updates temperature sensor configuration.
|
||||
|
||||
@@ -326,7 +334,7 @@ Fields:
|
||||
|
||||
Returns the updated config.
|
||||
|
||||
### POST /config/bms
|
||||
### POST /api/v1/config/bms
|
||||
|
||||
Updates BMS configuration.
|
||||
|
||||
@@ -348,13 +356,13 @@ random
|
||||
|
||||
Returns the updated config.
|
||||
|
||||
### POST /config/save
|
||||
### POST /api/v1/config/save
|
||||
|
||||
Persists the current active configuration.
|
||||
|
||||
Returns the current config.
|
||||
|
||||
### POST /config/factory-reset
|
||||
### POST /api/v1/config/factory-reset
|
||||
|
||||
Clears saved configuration and restores firmware defaults.
|
||||
|
||||
@@ -362,7 +370,7 @@ Returns the reset config.
|
||||
|
||||
## Relay Control
|
||||
|
||||
### POST /relay/set
|
||||
### POST /api/v1/relay/set
|
||||
|
||||
Preferred relay command endpoint.
|
||||
|
||||
@@ -407,7 +415,7 @@ Response:
|
||||
|
||||
## WiFi
|
||||
|
||||
### GET /config/wifi
|
||||
### GET /api/v1/config/wifi
|
||||
|
||||
Returns AP/STA WiFi configuration status. Passwords are not returned.
|
||||
|
||||
@@ -435,7 +443,7 @@ Returns AP/STA WiFi configuration status. Passwords are not returned.
|
||||
}
|
||||
```
|
||||
|
||||
### POST /config/wifi
|
||||
### POST /api/v1/config/wifi
|
||||
|
||||
Preferred multi-network request:
|
||||
|
||||
@@ -473,13 +481,13 @@ Runtime behavior:
|
||||
- Lower priority numbers are tried first.
|
||||
- If STA disconnects, saved networks are retried by priority.
|
||||
|
||||
### POST /wifi/connect
|
||||
### POST /api/v1/wifi/connect
|
||||
|
||||
Attempts STA connection using saved networks by priority.
|
||||
|
||||
Returns WiFi config status.
|
||||
|
||||
### POST /wifi/clear
|
||||
### POST /api/v1/wifi/clear
|
||||
|
||||
Clears saved STA WiFi networks.
|
||||
|
||||
@@ -487,7 +495,7 @@ Returns WiFi config status.
|
||||
|
||||
## Temperature Probe Setup
|
||||
|
||||
### POST /temps/scan
|
||||
### POST /api/v1/temps/scan
|
||||
|
||||
Scans the DS18B20 bus and returns unassigned probe addresses.
|
||||
|
||||
@@ -506,7 +514,7 @@ Scans the DS18B20 bus and returns unassigned probe addresses.
|
||||
|
||||
Already-assigned probe addresses are hidden from scan results until cleared.
|
||||
|
||||
### POST /temps/assign
|
||||
### POST /api/v1/temps/assign
|
||||
|
||||
Assigns a scanned probe to a logical temperature slot.
|
||||
|
||||
@@ -530,7 +538,7 @@ By slot number:
|
||||
|
||||
Returns the updated config.
|
||||
|
||||
### POST /temps/clear
|
||||
### POST /api/v1/temps/clear
|
||||
|
||||
Clears one or all temperature assignments.
|
||||
|
||||
@@ -560,7 +568,7 @@ Returns the updated config.
|
||||
|
||||
These endpoints are for BMS discovery and selection. Do not change JBD/Xiaoxiang BLE behavior without explicit approval.
|
||||
|
||||
### POST /bms/setup/enter
|
||||
### POST /api/v1/bms/setup/enter
|
||||
|
||||
Enters BMS setup mode.
|
||||
|
||||
@@ -574,7 +582,7 @@ Response:
|
||||
}
|
||||
```
|
||||
|
||||
### POST /bms/setup/exit
|
||||
### POST /api/v1/bms/setup/exit
|
||||
|
||||
Exits BMS setup mode.
|
||||
|
||||
@@ -588,7 +596,7 @@ Response:
|
||||
}
|
||||
```
|
||||
|
||||
### POST /bms/scan
|
||||
### POST /api/v1/bms/scan
|
||||
|
||||
Scans for BLE devices.
|
||||
|
||||
@@ -610,7 +618,7 @@ Response:
|
||||
|
||||
Some BMS devices advertise intermittently. Repeated scans may be needed.
|
||||
|
||||
### POST /bms/select
|
||||
### POST /api/v1/bms/select
|
||||
|
||||
Selects a BMS from the most recent scan result.
|
||||
|
||||
@@ -676,9 +684,9 @@ Some serial/UART errors use `message` instead of `error`; HTTP clients should re
|
||||
|
||||
## Compatibility
|
||||
|
||||
Current stable route prefix is the root API path, for example `GET /status`.
|
||||
Current stable API prefix is `/api/v1`, for example `GET /api/v1/status`.
|
||||
|
||||
Future versioning may move to `/api/v1`. Do not introduce versioned routes until consumers and docs are updated together.
|
||||
Pre-versioned root routes remain registered as local compatibility aliases. Do not add new root-only HTTP API routes.
|
||||
|
||||
New fields may be added to existing JSON objects. Consumers should ignore unknown fields.
|
||||
|
||||
@@ -687,8 +695,8 @@ New fields may be added to existing JSON objects. Consumers should ignore unknow
|
||||
These routes are not part of the current registered HTTP API:
|
||||
|
||||
```text
|
||||
POST /bms/reconnect
|
||||
POST /system/restart
|
||||
POST /api/v1/bms/reconnect
|
||||
POST /api/v1/system/restart
|
||||
```
|
||||
|
||||
If added later, update this document and add contract tests.
|
||||
|
||||
Reference in New Issue
Block a user