mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2026-03-06 08:10:16 -05:00
70 lines
1.6 KiB
Markdown
70 lines
1.6 KiB
Markdown
---
|
|
name: api-development
|
|
description: Develop and extend NetAlertX REST API endpoints. Use this when asked to create endpoint, add API route, implement API, or modify API responses.
|
|
---
|
|
|
|
# API Development
|
|
|
|
## Entry Point
|
|
|
|
Flask app: `server/api_server/api_server_start.py`
|
|
|
|
## Existing Routes
|
|
|
|
- `/device/<mac>` - Single device operations
|
|
- `/devices` - Device list
|
|
- `/devices/export/{csv,json}` - Export devices
|
|
- `/devices/import` - Import devices
|
|
- `/devices/totals` - Device counts
|
|
- `/devices/by-status` - Devices grouped by status
|
|
- `/nettools` - Network utilities
|
|
- `/events` - Event log
|
|
- `/sessions` - Session management
|
|
- `/dbquery` - Database queries
|
|
- `/metrics` - Prometheus metrics
|
|
- `/sync` - Synchronization
|
|
|
|
## Authorization
|
|
|
|
All routes require header:
|
|
|
|
```
|
|
Authorization: Bearer <API_TOKEN>
|
|
```
|
|
|
|
Retrieve token via `get_setting_value('API_TOKEN')`.
|
|
|
|
## Response Contract
|
|
|
|
**MANDATORY:** All responses must include `"success": true|false`
|
|
|
|
```python
|
|
return {"success": False, "error": "Description of what went wrong"}
|
|
```
|
|
|
|
On success:
|
|
|
|
```python
|
|
return {"success": True, "data": result}
|
|
```
|
|
|
|
```python
|
|
return {"success": False, "error": "Description of what went wrong"}
|
|
```
|
|
|
|
On success:
|
|
|
|
```python
|
|
return {"success": True, "data": result}
|
|
```
|
|
|
|
|
|
**Exception:** The legacy `/device/<mac>` GET endpoint does not follow this contract to maintain backward compatibility with the UI.
|
|
|
|
## Adding New Endpoints
|
|
|
|
1. Add route in `server/api_server/` directory
|
|
2. Follow authorization pattern
|
|
3. Return proper response contract
|
|
4. Update UI to read/write JSON cache (don't bypass pipeline)
|