| 1 |
# `includes/rest/` — REST route map |
| 2 |
|
| 3 |
Discoverability index for the REST surface. Routes are still registered in their owning subsystem files (where the callback closures and module state live), so moving the `register_rest_route()` calls into a single directory would have been a paperwork rename that broke nothing and improved nothing. This document is the central grep target instead. |
| 4 |
|
| 5 |
Plugin authors looking for the canonical route URL → handler map start here; the implementation file is one open away. |
| 6 |
|
| 7 |
## Namespace |
| 8 |
|
| 9 |
All in-tree routes register under `desktop-mode/v1`. Extensions are expected to register under `desktop-mode-<extension>/v1` (the `extensions/base/Desktop_Mode_Extension_Rest` base enforces this). |
| 10 |
|
| 11 |
## Routes |
| 12 |
|
| 13 |
| Route | Verb | Handler file | Permission | |
| 14 |
|---|---|---|---| |
| 15 |
| `/session` | GET / POST / DELETE | `includes/session.php` | logged-in + desktop mode enabled | |
| 16 |
| `/default-window` | POST | `includes/default-window.php` | logged-in + desktop mode enabled | |
| 17 |
| `/intros/seen` | POST | `includes/seen-intros.php` | logged-in + desktop mode enabled | |
| 18 |
| `/intros` | DELETE | `includes/seen-intros.php` | logged-in + desktop mode enabled | |
| 19 |
| `/os-settings` | GET / POST | `includes/os-settings.php` | logged-in + desktop mode enabled | |
| 20 |
| `/extended-options/*` | various | `includes/extended-options.php` | `manage_options` | |
| 21 |
| `/pwa-state` | GET / POST | `includes/pwa.php` | logged-in + desktop mode enabled | |
| 22 |
| `/devtools/*` | various | `includes/devtools.php` | `manage_options` | |
| 23 |
| `/presence` | GET / POST | `includes/presence.php` | logged-in + desktop mode enabled | |
| 24 |
| `/posts/*` | various | `includes/posts-window/window.php` | `edit_posts` | |
| 25 |
| `/my-wordpress/comments/*` | various | `includes/my-wordpress/comment-stats.php` | `read` | |
| 26 |
| `/my-wordpress/terms/*` | various | `includes/my-wordpress/term-stats.php` | `read` | |
| 27 |
| `/my-wordpress/users/*` | various | `includes/my-wordpress/user-stats.php` | `list_users` | |
| 28 |
| `/recycle-bin/*` | various | `includes/recycle-bin/rest.php` | `delete_posts` (per-route gate) | |
| 29 |
| `/desktop-files/*` | various | `includes/desktop-files/rest.php` | logged-in + per-file caps | |
| 30 |
| `/ai/search` | POST | `includes/ai-copilot/search.php` | logged-in + AI feature flag | |
| 31 |
| `/ai/platform-settings` | GET / POST | `includes/ai-copilot/platform-settings.php` | `manage_options` | |
| 32 |
| `/ai/reindex` | POST | `includes/ai-copilot/reindex.php` | `manage_options` | |
| 33 |
|
| 34 |
## Conventions |
| 35 |
|
| 36 |
- **Nonce.** Every state-changing route requires `X-WP-Nonce` (the standard REST nonce). Read routes that depend on per-user state also require it. |
| 37 |
- **Permission.** Permission callbacks use either `is_user_logged_in()` + capability checks or domain predicates. Shell-internal endpoints that only touch the caller's own per-user desktop state (`/session`, `/default-window`, `/intros`, `/os-settings`, `/pwa-state`, `/presence`) share the `desktop_mode_rest_require_enabled()` gate (`includes/helpers.php`): logged-in **and** `desktop_mode_is_enabled()`, returning `401` when logged out and `403` when desktop mode is off. `read` alone is deliberately not enough — every authenticated role carries it. Filtering with `desktop_mode_*` hooks lets plugins extend or harden access. |
| 38 |
- **Errors.** Failures return `WP_Error` with a stable `code`, a translated `message`, and a `data: { status: <int> }` block. Codes are documented per-endpoint in `docs/hooks-reference.md`. |
| 39 |
|
| 40 |
## Why no central registration |
| 41 |
|
| 42 |
PHP `register_rest_route()` calls execute on `rest_api_init`. The callback closures in the existing files capture per-module state — the recycle-bin store, the desktop-files registry, the AI provider — that lives in the same module. Moving the registration calls out of those files would force every callback to re-look-up its dependencies, increasing surface area without reducing coupling. The route → handler-file map above is the discoverability win we wanted; the per-module registrations are the layout that minimises blast radius. |
| 43 |
|
| 44 |
If a future extension adds REST routes that don't fit any existing module, the `extensions/base/Desktop_Mode_Extension_Rest` base class is the cheapest path. See `extensions/base/README.md`. |
| 45 |
|
