[Tracking] Tighten CBT REST API conventions across endpoints #844

Tracking issue for a cross-cutting cleanup of the CBT REST API surface. None of these are bugs — they're consistency / hardening items that should be applied uniformly across all endpoints rather than piecemeal in feature PRs.

Background

Review feedback on #843 (Edit Theme Settings endpoint) raised several "best practice" items that already apply to the existing CBT endpoints (/save, /update, /clone, /create-variation, /create-blank, /create-child, /font-families, /reset-theme, /export, /theme-settings). Fixing them only on new endpoints creates inconsistency, so this issue groups them for a single sweep.

Items to address

1. Add args schemas to register_rest_route. Currently no CBT endpoint declares args, which means WP can't auto-validate types, generate documentation, or filter via ?_fields=. Each endpoint registers payloads that are then validated manually inside the handler. Standardize on schema-based validation where reasonable.

2. defined( 'ABSPATH' ) || exit; guards at the top of every PHP file. Currently absent from the files under includes/create-theme/ (theme-save.php, theme-json.php, theme-utils.php, theme-settings-save.php, etc.).

3. if ( ! class_exists( 'CBT_Foo' ) ) guards around class declarations. Defensive against double-loading. Currently absent.

4. Response shape audit. Most endpoints return { "status": "SUCCESS", "message": "..." }. Reviewers note this is non-standard — WP REST convention is to use HTTP status codes and let the body carry data. Either keep the existing shape (it's load-bearing for the JS resolver pattern) and document why, or standardize on returning data only.

5. Type hints in handler signatures. Existing handlers use $request without WP_REST_Request type hints. Adding them is idiomatic since WP 5.x.

6. Optional payload size cap. WP's post_max_size and memory_limit already gate this, but a defensive cap inside file-writing endpoints (/save, /theme-settings) is reasonable belt-and-braces for very large theme.json payloads.

7. Entry-level structural validation across endpoints. Add /theme-settings REST endpoint + CBT_Theme_Settings_Save service #843 added required-key checks for customTemplates and templateParts in PR 0; consider extending to other endpoints that accept lists of structured entries.

Approach

Each item is small in isolation. Suggest one PR per item rather than a mega-PR, so each can be reviewed and reverted independently. Items 2 and 3 are mechanical and could share a PR.

Related

• Add /theme-settings REST endpoint + CBT_Theme_Settings_Save service #843 — Edit Theme Settings endpoint (the trigger for this cleanup; addresses the same items only for the new file)
• [Tracking] Edit Theme Settings: phased implementation #836 — Edit Theme Settings tracking issue
• The conventions established here will inform the per-tab PRs (Foundation + Color tab fully wired #838–Templates tab persistence #842)

Open to discussion on priority and whether items should be consolidated.