API Architecture
REST API design, request/response structure, error handling, and route organization.
The Care Nexus REST API is built on Express.js following consistent conventions for request handling, response formatting, and error management. Every API response uses the ApiResponse utility wrapper to ensure a predictable shape that the frontend can reliably parse.
Response Format
All API responses — success and error — follow this structure:
| Field | Type | Description |
|---|---|---|
| success | boolean | true for 2xx responses, false for errors |
| message | string | Human-readable status message |
| data | any | Response payload (null on errors) |
| error | string | Error description (null on success) |
| statusCode | number | HTTP status code mirrored in body |
Route Organization
/api/auth/*— Public authentication routes (login, register, forgot password)/api/doctor/*— Doctor-only routes (requires doctor role JWT)/api/patient/*— Patient-only routes (requires patient role JWT)/api/clinic/*— Clinic admin routes (requires clinic_admin role JWT)/api/ai/*— AI features (Gemini chat, transcription, parsing)/api/chat/*— Chat REST fallback (rooms list, message history)/api/notifications/*— Notification CRUD for all authenticated roles/api/public/*— Unauthenticated public routes (clinic listing, doctor search)
Error Handling
A global error handler middleware catches all unhandled errors thrown in controllers. Controllers use the asyncHandler wrapper to remove repetitive try/catch blocks.
Custom ApiError objects carry HTTP status codes and messages, which are transformed into the standard API response format by the global handler.
Validation
All incoming request bodies are validated using Joi schemas before reaching the controller. Invalid requests return 400 Bad Request with a clear validation message.
API versioning
The API is currently unversioned in the URL, but structured to support/api/v2 in the future without breaking existing clients.