Backend ‐ API Design Guidelines

Naming endpoints and fields

• Avoid redundant words, brand names, or trademarks
• Avoid acronyms unless they are universally understood (like ID)
• Use the plural form for endpoints that can return more than one resource (like /stations)
• Use the single form for endpoints that return details about one resource (like /stations/1)
• Use lowerCamelCase for all endpoints and JSON property names.
• Acronyms should be cased like normal words, not all uppercase (like id or userId, not ID or userID)

WebSocket Endpoints

The simulation uses WebSocket connections for real-time frame streaming:

Connection: ws://[host]/api/v1/ws/simulation/{simulation_id}

Authentication: Requires valid JWT token passed as query parameter or header

Frame Payload Structure:

{
  "type": "FRAME",
  "timestamp": "2026-01-27T10:30:00",
  "simulationTime": "day1:14:30",
  "drivers": [...],
  "tasks": [...],
  "stations": [...]
}

Simulation Control Events:

• PAUSE - Pause simulation
• RESUME - Resume simulation
• SPEED_CHANGE - Adjust simulation speed (1x, 2x, 4x, 8x)
• SEEK - Jump to specific frame

Recent Endpoint Additions

Simulation Control:

• POST /api/v1/simulation/{id}/resume - Resume paused simulation
• POST /api/v1/simulation/{id}/seek - Seek to specific simulation frame
• POST /api/v1/simulation/{id}/branch - Create branch from simulation state

Driver Task Management:

• PUT /api/v1/drivers/{driver_id}/tasks/reorder - Reorder driver's task queue

Note: The "Resource" entity was split into "Driver" and "Vehicle" entities in December 2025, so endpoints now use /drivers instead of /resources.