api-routes.md 2.6 KB
Read this when changing the JSON API contract, request authorization, or a React call to /api/v1.
API Routes
All routes are registered in src/OpenMind/Api/Api.php. Responses are JSON with Cache-Control: no-store. CSRF means X-CSRF-Token must equal the token stored in the PHP session.
| Method | Path | Handler | Description | Authorization |
|---|---|---|---|---|
| GET | /api/v1/auth/session |
AuthController::session |
Returns authenticated state, safe user DTO, roles, and CSRF token. | Public |
| POST | /api/v1/auth/login |
AuthController::login |
Validates JSON credentials, regenerates the session ID, stores the user, and returns session state. | Public |
| POST | /api/v1/auth/logout |
AuthController::logout |
Clears session and returns anonymous state. | CSRF |
| GET | /api/v1/navigation |
NavigationController::index |
Returns permission-filtered, ordered menu entries. | Authenticated |
| GET | /api/v1/admin/config |
AdminController::load |
Returns decrypted configuration text. | admin |
| PUT | /api/v1/admin/config |
AdminController::save |
Encrypts and replaces configuration text. | admin + CSRF |
| GET | /api/v1/admin/users |
UserController::index |
Returns safe user DTOs and configured role choices. | admin |
| POST | /api/v1/admin/users |
UserController::create |
Creates a user from username, password, and configured roles. | admin + CSRF |
| PUT | /api/v1/admin/users/@id |
UserController::update |
Updates selected user fields. | admin + CSRF |
| DELETE | /api/v1/admin/users/@id |
UserController::delete |
Deletes an eligible user. | admin + CSRF |
| GET | /api/v1/notifications |
NotificationController::index |
Returns notifications grouped by caption. | Authenticated |
| DELETE | /api/v1/notifications |
NotificationController::delete |
Clears every notification. | Authenticated + CSRF |
| DELETE | /api/v1/notifications/@code |
NotificationController::delete |
Deletes notifications matching a non-negative integer code. | Authenticated + CSRF |
Contract Notes
Controller::decodeJsonRequest()accepts only a JSON object; malformed or empty bodies are rejected.- The authentication/session response is the source of the current CSRF token. The client caches it only in memory.
- Unauthorized routes return 401; insufficient roles return 403; user-management business conflicts return 409 with a stable
code. - Route registration is separate from legacy system methods that are not registered in
System::setSystemRoutes().
See identity/spec.md, configuration/spec.md, and rules/add-api-endpoint.md.