diff --git a/documentation/V3_FRONTEND_API_GUIDE.md b/documentation/V3_FRONTEND_API_GUIDE.md index 4a0bb92..389dde0 100644 --- a/documentation/V3_FRONTEND_API_GUIDE.md +++ b/documentation/V3_FRONTEND_API_GUIDE.md @@ -191,7 +191,69 @@ const downloadUrl = `${BASE_URL}/v3/crud/hosted_file/${fileId}/?jwt=${jwtToken}` --- -## 7. Best Practices for V3 + + +## 7. The "ID Vision" Standard (2026 Refactor) + + + +V3 has moved to a **String-Only ID Vision**. In this paradigm, the frontend (SvelteKit) and external agents NEVER handle or store internal database integers. + + + +### A. Automatic ID Mapping (Output) + +All V3 endpoints now automatically rename internal `id_random` fields to clean, short names in the JSON response. + +- **`id`**: The unique random identifier for the primary record. + +- **`account_id`**: The unique random identifier for the parent account. + +- **`site_id`, `person_id`, etc**: All related IDs follow this clean naming. + + + +**Example Response:** + +```json + +{ + + "id": "OGQK-02-04-94", + + "name": "Scott's Journal", + + "account_id": "nqOzejLCDXM" + +} + +``` + + + +### B. Intelligent Mapping (Input/Search) + +The backend is now "Vision Aware." You can send string IDs back to the API using the same clean names. + +- **Search Filters**: You can filter by `account_id` using the random string value. The API handles the mapping to the DB integer automatically. + +- **Create/Update**: You can send `account_id: "nqOzejLCDXM"` in a payload. The `sanitize_payload` logic resolves this to the correct integer before saving. + + + +**Preferred Filter Pattern:** + +```json + +{ + + "and": [{ "field": "account_id", "op": "eq", "value": "nqOzejLCDXM" }] + +} + +``` + + --- @@ -201,63 +263,25 @@ const downloadUrl = `${BASE_URL}/v3/crud/hosted_file/${fileId}/?jwt=${jwtToken}` -To ensure stability across the Aether mesh, all frontend components must adhere to these established patterns. +### A. Permissive Update Mode (Upcoming) + +**Status:** In Development. -### A. The "Whitelist" Standard for Saves - -**Problem:** Sending the entire object returned by a GET request back to a PATCH endpoint will cause a `400 Bad Request`. This happens because the object contains technical metadata (like `journal_id`, `created_on`, `for_type`) that the API cannot "SET". +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`. -**Standard:** When preparing a save payload, explicitly whitelist ONLY the user-editable fields. +- **Header:** `x-ae-ignore-extra-fields: true` -```ts - -// ✅ CORRECT: Whitelist only editable fields - -const data_kv = { - - name: tmp_obj.name, - - content: tmp_obj.content, - - tags: tmp_obj.tags, - - category_code: tmp_obj.category_code - -}; +This allows you to send back larger chunks of the object without meticulously whitelisting every field, though whitelisting remains a best practice for performance. -// ❌ WRONG: Passing the whole object or just blacklisting a few - -const data_kv = { ...tmp_obj }; - -delete data_kv.id; // Still contains other computed columns! - -``` - - - -### B. The Triple-ID Save Pattern - -**Standard:** When sending an ID in a POST/PATCH payload (e.g. creating a child object), use the random string version with the `_id_random` suffix. - -* **Property:** `[obj_type]_id_random` - -* **Value:** A string (e.g., `qpgvOh5nOYI`) - - - -**Warning:** Sending a string value under an integer key (e.g. `journal_id: "qpgvOh5nOYI"`) will trigger a Pydantic validation error on the backend. - - - -### C. Handle 'NULL' vs '0' for Booleans +### B. Handle 'NULL' vs '0' for Booleans **Pitfall:** Fields like `hide` or `priority` can be `NULL` in the database.