diff --git a/documentation/V3_FRONTEND_API_GUIDE.md b/documentation/V3_FRONTEND_API_GUIDE.md index 389dde0..ee43ca9 100644 --- a/documentation/V3_FRONTEND_API_GUIDE.md +++ b/documentation/V3_FRONTEND_API_GUIDE.md @@ -261,28 +261,86 @@ The backend is now "Vision Aware." You can send string IDs back to the API using ## 8. Standard Patterns & Common Pitfalls (2026 Update) +### A. Permissive Update Mode (Available) +**Usage:** High-performance state syncing. -### A. Permissive Update Mode (Upcoming) - -**Status:** In Development. - - - -To simplify frontend state management, V3 is introducing a **Permissive Update Mode**. When enabled, the backend will **ignore** extra fields in your `PATCH` payload (like `_processed_at` or `created_on`) instead of returning a `400 Bad Request`. - - +To simplify frontend state management, V3 supports a **Permissive Update Mode**. When enabled, the backend will **ignore** extra fields in your `PATCH` or `POST` payload (like `_processed_at`, `created_on`, or UI-specific keys) instead of returning a `400 Bad Request`. - **Header:** `x-ae-ignore-extra-fields: true` +**When to use:** +- When sending back an object fetched via `GET` that contains read-only technical metadata. +- When the frontend adds temporary "state" keys to objects that shouldn't be saved to the DB. - -This allows you to send back larger chunks of the object without meticulously whitelisting every field, though whitelisting remains a best practice for performance. - - +--- ### B. Handle 'NULL' vs '0' for Booleans + + **Pitfall:** Fields like `hide` or `priority` can be `NULL` in the database. -**Standard:** Ensure your synchronization logic in components handles `null`, `undefined`, and `0` identically for boolean checks to prevent "ghost" changes being detected by Svelte 5. \ No newline at end of file + + +**Standard:** Ensure your synchronization logic in components handles `null`, `undefined`, and `0` identically for boolean checks to prevent "ghost" changes being detected by Svelte 5. + + + +--- + + + +### C. Structured Error Handling (Rich Bubbling) + + + +V3 provides machine-readable error objects in the `meta.details` field for most failures (400/500). Instead of parsing strings, your error handler should check the `category` and `code`. + + + +**Example Error Response:** + +```json + +{ + + "meta": { + + "success": false, + + "status_code": 400, + + "status_message": "Failed to update object.", + + "details": { + + "category": "database_schema", + + "code": 1054, + + "message": "Unknown column 'unauthorized_field' in 'SET'", + + "recoverable": false + + } + + } + +} + +``` + + + +**Common Categories:** + +- **`database_duplicate`**: Attempted to create a record with a non-unique value (Code 1062). + +- **`database_constraint`**: Foreign key or integrity violation (Codes 1451, 1452). + +- **`database_schema`**: Invalid column name or table configuration (Codes 1054, 1146). + +- **`database_connection`**: Temporary DB unavailability (`recoverable: true`). + +- **`validation`**: Pydantic validation failed (Check `details` for field-specific errors). \ No newline at end of file