phpengine/specs/rules/add-api-endpoint.md

Read this when adding or changing a versioned JSON API endpoint and its React caller.

Add or Change an API Endpoint

1. Choose the authorization contract. Classify the route as public, authenticated, role-protected, and/or state-changing. See identity spec.

2. Register the route in src/OpenMind/Api/Api.php using AddRoute() and the /api/v1 path convention.

   $this->AddRoute('GET /api/v1/example', __NAMESPACE__ . '\\ExampleController->index');
   

3. Implement the controller as a Controller subclass. Use requireAuthentication() / requireRole() first. For mutations, reject invalid CSRF before persistence.

   if (!$this->requireRole('admin')) return;
   if (!$this->validateCsrfToken()) {
      $this->sendError('Invalid CSRF token', 403);
      return;
   }
   

4. Validate JSON input with decodeJsonRequest() and return only an explicit JSON DTO via sendJson(). Do not serialize mappers or return credential/configuration fields.

5. Preserve persistence invariants. Use parameterized mapper predicates; wrap serialized multi-step mutation checks in a transaction when needed. See MySQL integration.

6. Add the frontend client call to ui/app/src/api/client.js using apiRequest(). Do not bypass its base-path, cookie, JSON-error, or CSRF handling.

7. Connect the UI and documentation. Add/update the feature and route only when the server authorizes it, then update API routes and the relevant domain/integration spec.

No automated test command is configured; review the method/path, authorization, CSRF, request validation, safe response shape, and affected frontend call before delivery.