Skip to content

API.md

Latest commit

 

History

History
250 lines (202 loc) · 5.08 KB

API.md

File metadata and controls

250 lines (202 loc) · 5.08 KB

API Documentation

Base URL

All API endpoints are accessed through NGINX Ingress, which routes to the API Gateway:

http://basestation.local:{ingress-port}/api/v1

To find your ingress port:

kubectl get svc -n ingress-nginx ingress-nginx-controller

Rate Limiting

Gateway enforces per-service rate limits:

Endpoint Rate Limit Burst
Auth (/auth/**) 10 req/s 20
Stations (/stations/**) 50 req/s 100
Monitoring (/metrics/**) 100 req/s 200
Alerts (/alerts/**) 50 req/s 100
SON (/son/**) 50 req/s 100
Diagnostics (/diagnostics/**) 30 req/s 60
Thresholds (/thresholds/**) 30 req/s 60
Notifications (/notifications/**) 30 req/s 60
Reports (/reports/**) 5 req/s 10

Authentication

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}

# Response
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "username": "admin",
  "role": "ROLE_ADMIN"
}

Use Token

Include the token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Stations API

Create Station

POST /api/v1/stations
Authorization: Bearer <token>
Content-Type: application/json

{
  "stationName": "NYC-Manhattan-001",
  "location": "Manhattan, NY",
  "latitude": 40.7580,
  "longitude": -73.9855,
  "stationType": "MACRO_CELL",
  "status": "ACTIVE",
  "powerConsumption": 3500
}

Get All Stations

GET /api/v1/stations
GET /api/v1/stations?status=ACTIVE
GET /api/v1/stations?type=MACRO_CELL

Get Station by ID

GET /api/v1/stations/{id}

Update Station

PUT /api/v1/stations/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "stationName": "NYC-Manhattan-001-Updated",
  "status": "MAINTENANCE"
}

Delete Station

DELETE /api/v1/stations/{id}
Authorization: Bearer <token>

Geographic Search

# Find stations within radius
GET /api/v1/stations/search/nearby?lat=40.7128&lon=-74.0060&radiusKm=10

# Find stations in bounding box
GET /api/v1/stations/search/area?minLat=40.0&maxLat=41.0&minLon=-75.0&maxLon=-73.0

Metrics API

Record Metric

POST /api/v1/metrics
Authorization: Bearer <token>
Content-Type: application/json

{
  "stationId": 1,
  "stationName": "NYC-Manhattan-001",
  "metricType": "CPU_USAGE",
  "value": 65.5,
  "unit": "%"
}

Query Metrics

# Get all metrics
GET /api/v1/metrics

# Get by station
GET /api/v1/metrics/station/{stationId}

# Get with time range
GET /api/v1/metrics?startTime=2026-01-20T00:00:00

# Batch latest metrics (prevents N+1)
POST /api/v1/metrics/batch/latest
Content-Type: application/json

{"stationIds": [1, 2, 3]}

Metrics Validation

All metrics are validated before storage:

Metric Type Valid Range Unit
CPU_USAGE 0-100 %
MEMORY_USAGE 0-100 %
TEMPERATURE -50 to 150 C
POWER_CONSUMPTION 0-50,000 W
SIGNAL_STRENGTH -120 to -20 dBm
DATA_THROUGHPUT 0-100,000 Mbps
CONNECTION_COUNT 0-10,000 count

Invalid values are rejected:

// Response for CPU_USAGE = 150
{
  "message": "CPU_USAGE must be between 0 and 100%, received: 150.00"
}

Notifications API

Get Notifications

GET /api/v1/notifications
GET /api/v1/notifications/station/{stationId}
GET /api/v1/notifications/page?page=0&size=20
GET /api/v1/notifications/counts
GET /api/v1/notifications/recent

Delete Notification

DELETE /api/v1/notifications/{id}
Authorization: Bearer <token>

AI Diagnostics API

The AI Diagnostic service exposes a direct endpoint (internal use):

POST http://ai-diagnostic:9091/diagnose
Content-Type: application/json
X-HMAC-Signature: <hmac-signature>

{
  "id": "alert-123",
  "timestamp": "2026-01-27T10:30:00Z",
  "station_id": "1",
  "category": "thermal",
  "severity": "HIGH",
  "code": "TEMPERATURE_HIGH",
  "message": "Temperature exceeds threshold",
  "metrics": {"temperature": 85.5, "threshold": 75.0}
}

# Response
{
  "problem_id": "alert-123",
  "action": "Increase cooling system capacity",
  "commands": ["increase_cooling", "check_hvac"],
  "expected_outcome": "Temperature should drop below threshold",
  "risk_level": "HIGH",
  "confidence": 0.92,
  "reasoning": "High temperature detected, cooling system adjustment needed"
}

Error Responses

All errors follow a consistent format:

{
  "timestamp": "2026-01-27T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed: username must not be blank",
  "path": "/api/v1/auth/login"
}

Health Endpoints

Each service exposes health endpoints. Externally accessible via ingress:

# Via ingress
GET http://basestation.local:{ingress-port}/api/actuator/health

Internal health checks (within the cluster):

GET http://auth-service:8084/actuator/health
GET http://base-station-service:8081/actuator/health
GET http://monitoring-service:8082/actuator/health
GET http://ai-diagnostic:9091/health