TJWaterServerBinary/BACKEND_NAMING_AUDIT.md

Backend Naming Audit

DOC-003 audit for the internal TJWaterServerBinary backend.

Scope

Reviewed FastAPI route decorators under app/api/v1/endpoints, router prefixes in app/api/v1/router.py, and public request/response schema fields in app/api and app/domain.

The backend is mounted only under /api/v1 from app/main.py; the old no-prefix router include remains commented out.

Current Good Surface

These newer routes already follow the naming rule for public HTTP paths:

• Metadata/admin: /api/v1/admin/projects, /api/v1/admin/users/sync, /api/v1/admin/projects/{project_id}/members
• Audit: /api/v1/audit/logs, /api/v1/audit/logs/count
• Agent auth: /api/v1/agent/auth/context
• Business APIs: /api/v1/burst-detection/detect, /api/v1/burst-location/locate, /api/v1/leakage/identify
• Time-series APIs: /api/v1/scada/by-ids-time-range, /api/v1/scada/by-ids-field-time-range, /api/v1/composite/clean-scada
• Project data APIs: /api/v1/scada-info, /api/v1/scheme-list, /api/v1/burst-locate-result
• Web integrations: /api/v1/web-search, /api/v1/geocode

Path template parameters such as {project_id}, {user_id}, {device_id}, {scheme_name}, and {link_id} intentionally remain snake_case.

Legacy URL Categories

Keep With Compatibility

These now have kebab-case aliases. The frontend has been migrated to the replacement paths; keep the old paths as deprecated compatibility aliases for Agent planning, tests, customer scripts, or external callers:

Current URL	Suggested replacement
/api/v1/openproject/	/api/v1/projects/open
/api/v1/project_info/	/api/v1/project-info
/api/v1/getallschemes/	/api/v1/schemes
/api/v1/getallsensorplacements/	/api/v1/sensor-placement-schemes
/api/v1/sensorplacementscheme/create	/api/v1/sensor-placement-schemes
/api/v1/burst_analysis/	/api/v1/burst-analysis
/api/v1/valve_isolation_analysis/	/api/v1/valve-isolation-analysis
/api/v1/flushing_analysis/	/api/v1/flushing-analysis
/api/v1/contaminant_simulation/	/api/v1/contaminant-simulation
/api/v1/runsimulationmanuallybydate/	/api/v1/simulations/run-by-date

Broad Legacy Surface

These route groups expose many command-style concatenated paths. They should not be copied into new work; replace only when a caller migration is planned:

• Project lifecycle: listprojects, createproject, deleteproject, isprojectopen, closeproject, copyproject, importinp, exportinp, readinp, dumpinp, lockproject, unlockproject
• Network object CRUD: addjunction, getjunctionelevation, setpipediameter, getvalvesetting, and similar junction/pipe/pump/tank/reservoir/valve routes
• Region/DMA/VD commands: calculatedistrictmeteringareaforregion, getdistrictmeteringarea, generatevirtualdistrict, and related routes
• SCADA native CRUD: getscadadevice, setscadadevicedata, cleanscadaelement, and related routes
• Snapshot/cache utilities: takesnapshotforoperation, syncwithserver, clearrediskey, queryredis
• Advanced simulation endpoints with underscore paths: pressure_regulation, daily_scheduling_analysis, network_update, pressure_sensor_placement_kmeans

Direct Cleanup Candidates

These are likely safe only after confirming no caller uses them:

• /api/v1/test_dict/: development/test utility in misc.py.
• /api/v1/takenapshotforcurrentoperation: typo compatibility path; keep deprecated if any client may still call it.
• /api/v1/getpumpenergyproperties// and /api/v1/setpumpenergyproperties//: double-slash paths in options endpoints.

Field Naming

Most public JSON, query, and SSE fields are already snake_case, including project_id, user_id, scheme_name, scheme_type, start_time, end_time, device_ids, session_id, and request_id.

Known legacy exception:

• BurstAnalysis.burst_ID in app/api/v1/endpoints/simulation.py should become burst_id on a new API contract. Preserve burst_ID only for the legacy body shape.

Headers keep standard HTTP casing:

• X-Project-Id

Recommendation

Do not rename existing legacy routes in place. For each active legacy route, keep the new kebab-case alias as the documented path, keep the old route marked deprecated, migrate remaining Agent/customer/script callers, then remove only after a documented compatibility window.