phpengine/specs/api-routes.md

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/Core/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 with numeric role IDs, 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.	Role ID 1
PUT	/api/v1/admin/config	AdminController::save	Encrypts and replaces configuration text.	Role ID 1 + CSRF
GET	/api/v1/admin/users	UserController::index	Returns safe user DTOs with numeric role IDs and persistent role choices.	Role ID 1
POST	/api/v1/admin/users	UserController::create	Creates a user from username, password, and existing role IDs.	Role ID 1 + CSRF
PUT	/api/v1/admin/users/@id	UserController::update	Updates selected user fields and existing role IDs.	Role ID 1 + CSRF
DELETE	/api/v1/admin/users/@id	UserController::delete	Deletes an eligible user.	Role ID 1 + CSRF
GET	/api/v1/admin/roles	RoleController::list	Lists the persistent role catalog as safe {id, name, description} DTOs.	Role ID 1
POST	/api/v1/admin/roles	RoleController::create	Creates a role catalog record.	Role ID 1 + CSRF
PUT	/api/v1/admin/roles/@id	RoleController::update	Updates role metadata without changing its ID.	Role ID 1 + CSRF
DELETE	/api/v1/admin/roles/@id	RoleController::delete	Deletes a role only when it is not ID 1 and is not assigned to any user.	Role ID 1 + CSRF
GET	/api/v1/inventory/items	InventoryController::index	Lists Inventory Monitor demo item DTOs.	Role ID 2
POST	/api/v1/inventory/items	InventoryController::create	Creates an Inventory Monitor demo item and publishes a shared notification.	Role ID 2 + CSRF
PUT	/api/v1/inventory/items/@id	InventoryController::update	Updates an Inventory Monitor demo item and publishes a shared notification.	Role ID 2 + CSRF
DELETE	/api/v1/inventory/items/@id	InventoryController::delete	Deletes an Inventory Monitor demo item and publishes a shared notification.	Role ID 2 + 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; role, user, and inventory business conflicts return 409 with a stable code.
• Role authorization uses persistent numeric IDs: ID 1 is Administrator and ID 2 is Inventory operator. Renaming a role does not change access.
• Role deletion rejects the protected Administrator role (ID 1) and any role assigned to a user; these business conflicts return 409.
• Inventory routes require role ID 2; ID 1 does not implicitly grant inventory access. State-changing role, user, and inventory requests require the session CSRF token.
• 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.