Gateway API

Development Preview

This page is written against the routes and parsers actually registered at commit b1a16cbc (ApiRouter plus the individual RouteGroups); it does not carry over endpoint counts or unimplemented fields from the project's older documentation. A route's existence does not mean the end-to-end workflow is complete, especially driver registration, MQTT reverse control, factory reset, and OTA.

1. Base URL and Responses

Default base URL:

http://<gateway-ip>:8080

Except for explicitly noted endpoints such as Prometheus metrics, JSON responses are uniformly wrapped as:

{
  "code": 200,
  "msg": "ok",
  "data": {}
}

Successful creation typically uses HTTP 201 with msg: "created"; errors use the corresponding HTTP status code and msg (400 bad parameters / 401 unauthorized / 404 not found / 409 conflict / 500, 502, 503 server errors). GET /api/metrics returns text/plain metrics directly, without the JSON wrapper above.

2. Login and Token

POST /api/auth/login requires no existing token. Request:

{
  "username": "admin",
  "password": "<changed-password>"
}

curl -fsS http://127.0.0.1:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<changed-password>"}'

On success, data contains token, username, role, createdAt, and expiresAt. Protected routes use:

Authorization: Bearer <token>

The initial default password is admin123 and must be changed immediately; the current middleware verifies token presence and validity, so do not claim that role-level authorization is enforced on every route.

Endpoints that require no token (authentication whitelist and unauthenticated endpoints):

Method	Path	Description
POST	/api/auth/login	Log in and obtain a token
POST	/api/auth/logout	Log out (on the whitelist)
GET	/api/health	Process health, version, uptime, MQTT and Tag counts
GET	/api/metrics	Prometheus text metrics

Exposure of these unauthenticated endpoints should be restricted by network boundaries.

3. Overview API

Method	Path	Current behavior
GET	/api/health	Health check (unauthenticated): status, version, uptime, MQTT connection, Tag count
GET	/api/overview/status	System status: CPU/memory/temperature/disk usage and timestamp
GET	/api/overview/devices	Internal device total/online/offline statistics
GET	/api/overview/traffic	MQTT byte, message, publish, subscribe, and reconnect statistics

4. Device and Tag Management API

Method	Path	Current behavior
GET	/api/devices	Sub-device list
POST	/api/devices	Add a sub-device; success returns 201; a duplicate ID returns 409
PUT	/api/devices/:id	Replace the device model; the route ID overrides the request ID; not found returns 404
DELETE	/api/devices/:id	Delete the device and clean up its associated Tags in the TagEngine
GET	/api/devices/:id/tags	Tag list of the specified device
POST	/api/devices/:id/tags	Add a Tag; the route device ID overrides the request device ID
PUT	/api/devices/:id/tags/:tagId	Modify a Tag; the route ID overrides the request ID
DELETE	/api/devices/:id/tags/:tagId	Delete a Tag

Device creation example:

{
  "deviceId": "modbus-dev-001",
  "productId": "demo-product",
  "deviceNum": "modbus-001",
  "deviceName": "Modbus development device 001",
  "protocolType": "modbus"
}

Tag creation example:

{
  "id": "holding-0",
  "name": "Holding register 0",
  "sourceType": 0,
  "slaveAddr": 1,
  "registerAddr": 0,
  "registerCount": 1,
  "scale": 1,
  "offset": 0,
  "pollIntervalMs": 1000,
  "reportOnChange": false,
  "enabled": true
}

sourceType: 0 is Modbus, and register addresses are zero-based. The request parser does not read dataType, functionCode, or byte-order fields; see Configuration. Successfully creating a device or Tag does not mean the driver has been registered; see the current blockers in Quick Start.

5. GPIO API

Method	Path	Current behavior
GET	/api/gpio/di	DI channel state list (channel/name/state/changed/timestamp)
GET	/api/gpio/do	DO channel state list
POST	/api/gpio/do/:channel	DO control; request body {"state": true}
GET	/api/gpio/ai	AI channel values (rawValue/engValue/unit)

Real GPIO depends on the compile-time flag FASTBEE_ENABLE_GPIO=ON and libgpiod; the default build uses the simulated backend.

6. MQTT API

Method	Path	Current behavior
GET	/api/mqtt/config	Returns a summary of the connection configuration; active field names include useTls, and keepAlive is also included when the client is initialized
PUT	/api/mqtt/config	Only updates broker, port, clientId, username, and password and saves them; does not reconnect
GET	/api/mqtt/status	Returns connection state, broker, and message/error/reconnect statistics

The Web UI's "Save and Reconnect" copy and the submitted TLS, KeepAlive, and QoS fields do not mean the active PUT handles these behaviors. A read-only configuration mount can also cause saving to fail.

Note: the source code contains a certificate management route implementation (POST/GET/DELETE /api/mqtt/certificates), but the current registration flow does not mount that route group, so it must not be treated as an available endpoint.

7. System Management API

Method	Path	Notes
GET	/api/system/info	Version, build time, platform, hostname, and uptime
POST	/api/system/reboot	Executes the real system reboot command about 1 second after responding; token and network access must be strictly restricted
POST	/api/system/factory-reset	Placeholder: only logs and returns {"resetting":true}; no configuration cleanup is performed
GET	/api/system/config	Export configuration (via ConfigManager, genuinely functional)
POST	/api/system/config	Import configuration (via ConfigManager, genuinely functional)
POST	/api/system/upgrade	Placeholder: only checks the firmware field in the multipart body and returns the file name, size, and uploading; OTA installation, verification, and rollback are not implemented
GET	/api/system/time	Current time
POST	/api/system/time/sync	NTP synchronization; accepts server and timeoutMs
GET / POST	/api/system/timezone	Read or set the time zone

The factory-reset and OTA responses must not be taken as evidence of production success.

8. Authentication and User API

Method	Path	Current behavior
POST	/api/auth/login	Log in (SHA-256 password hash verification); returns a token
POST	/api/auth/logout	Invalidate the current token
GET	/api/users	User list
POST	/api/users	Add a user (username/password/role; roles such as admin/operator/viewer); success returns 201
PUT	/api/users/:id	Modify a user's role, enabled state, or password

The role permission model (admin/operator/viewer) is defined, but the current middleware only verifies the token; route-level role authorization is not complete.

9. Debug API

Method	Path	Current behavior and risks
GET	/api/debug/tags	Performs one full pollOnce() and returns Tag and engine statistics
POST	/api/debug/read	Ignores the requested device/Tag IDs and performs a full pollOnce()
POST	/api/debug/write	Calls TagEngine::writeTag() by tagId and value; a registered driver is still required
POST	/api/debug/ping	Concatenates host into a system command; command injection risk
GET	/api/debug/logs	Returns roughly the last 50 entries of the in-memory log

Manual write request:

{
  "tagId": "holding-0",
  "value": 1
}

value can be a boolean, integer, float, or string. A stub's success: true may only be a simulated result and does not prove a physical write. Production code does not call subscribeFunction, so this endpoint is not a substitute for MQTT cloud-side reverse control either.

Debug API Security

Do not expose /api/debug/* to untrusted networks. /api/debug/ping in particular carries a command injection risk and should be fixed or isolated first; full reads and writes should also be evaluated for fieldbus load and physical impact.

10. Alerts API

Active alert and history endpoints of the AlertManager:

Method	Path	Current behavior
GET	/api/alerts	Active alert list
POST	/api/alerts	Manually trigger an alert (source/level/message/extra); success returns 201
POST	/api/alerts/:id/ack	Acknowledge an alert
POST	/api/alerts/:id/silence	Silence an alert
DELETE	/api/alerts/:id	Clear an alert
DELETE	/api/alerts	Clear all acknowledged alerts
GET	/api/alerts/history	Alert history; supports ?limit= (default 100)
GET	/api/alerts/stats	Alert statistics

11. Alarm Engine API (alarms)

Industrial alarm rules and active alarm endpoints (note the plural path /api/alarms, unlike /api/alarm in the project's older documentation):

Method	Path	Current behavior
GET	/api/alarms/rules	Alarm rule list
POST	/api/alarms/rules	Create an alarm rule (fields in section 8 of Configuration); success returns 201
PUT	/api/alarms/rules/:id	Update an alarm rule; the ID in the URL takes precedence
DELETE	/api/alarms/rules/:id	Delete an alarm rule
GET	/api/alarms/rules/by-tag/:tagId	Query rules by Tag
GET	/api/alarms/active	Active alarm list
GET	/api/alarms/active/by-tag/:tagId	Query active alarms by Tag
POST	/api/alarms/:ruleId/ack	Acknowledge an alarm
POST	/api/alarms/:ruleId/silence	Silence an alarm
GET	/api/alarms/stats	Alarm statistics
GET	/api/alarms/export	Export all rules
POST	/api/alarms/import	Import rules (replace controls whether to replace all existing rules)

12. Peripheral Management API (peripherals)

Peripheral configuration center endpoints (see Peripherals and Linkage for the peripheral model):

Method	Path	Current behavior
GET	/api/peripherals	Peripheral list
POST	/api/peripherals	Add a peripheral (unique ID, pin conflict validation); success returns 201
PUT	/api/peripherals/:id	Update a peripheral (ID cannot be changed)
DELETE	/api/peripherals/:id	Delete a peripheral
POST	/api/peripherals/:id/enable	Enable a peripheral (validates pin conflicts)
POST	/api/peripherals/:id/disable	Disable a peripheral
POST	/api/peripherals/:id/test	Test action: DO toggle / LED light-up / buzzer beep; other types return 400
GET	/api/peripherals/export	Export peripheral configuration
POST	/api/peripherals/import	Import peripheral configuration

13. Peripheral Execution Rules API (periph-exec)

Linkage rule engine endpoints (see Peripherals and Linkage for the trigger/action model):

Method	Path	Current behavior
GET	/api/periph-exec	Rule list (including last execution time and result)
POST	/api/periph-exec	Create a rule; success returns 201
PUT	/api/periph-exec/:id	Update a rule
DELETE	/api/periph-exec/:id	Delete a rule
POST	/api/periph-exec/:id/enable	Enable/disable (request body {"enabled": false})
POST	/api/periph-exec/:id/run-once	Run once manually (optionally with {"value": "..."})
GET	/api/periph-exec/results	Recent execution results
GET	/api/periph-exec/export	Export rules
POST	/api/periph-exec/import	Import rules

14. Driver Health and Tag Aggregation API

Method	Path	Current behavior
GET	/api/drivers/health	Health summary of all drivers (total/healthy/isolated plus per-driver statistics)
GET	/api/drivers/:name/health	Health details of a single driver; not found returns 404
GET	/api/aggregator/rules	Aggregation rule list
GET	/api/aggregator/rules/:id/result	Aggregation result (value/sampleCount/lastUpdateMs/valid)

There is currently no registered endpoint for creating aggregation rules; driver health data must be interpreted against the premise that drivers are not yet registered with the TagEngine.

15. Prometheus Metrics API

Method	Path	Current behavior
GET	/api/metrics	Prometheus text metrics (unauthenticated), including uptime, system resources, Tag count, MQTT statistics, and more