Scott.Idem/OSIT-AE-API-FastAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: overhaul Data Store cascading guide for frontend agents

Browse Source 
- Replaced Section 8 with 'The Hierarchy of Truth' examples.
- Added explicit rules for Vision IDs and automatic JSON parsing.
- Clarified dynamic return behavior based on the 'limit' parameter.
- Cleaned up formatting and synced to agents_sync documentation path.
This commit is contained in:
Scott Idem
2026-01-28 17:36:33 -05:00
parent 0606cecb61
commit 9dd941eb36
2 changed files with 23 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
documentation/GUIDE__V3_FRONTEND_API.md
View File

@@ -142,7 +142,7 @@ V3 returns machine-readable error objects in `meta.details` for failures.
## 8. Data Store Cascading Lookup (V3)
V3 provides a specialized endpoint for retrieving configuration or content snippets by a human-friendly `code`. This uses a **hierarchical fallback** logic to find the best fit for the current context.
V3 provides a specialized endpoint for retrieving configuration or content snippets by a human-friendly `code`. This uses a **hierarchical fallback** logic to find the "best fit" record for the current user and object context.
### A. The V3 Lookup Endpoint
**Path:** `GET /v3/data_store/code/{code}`
@@ -151,16 +151,28 @@ V3 provides a specialized endpoint for retrieving configuration or content snipp
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `for_type` | String | No | Parent object type (e.g., `event`, `person`). |
| `for_id` | String | No | Parent object random ID. |
| `for_id` | String | No | Parent object random ID (Vision ID). |
| `limit` | Integer | No | **Dynamic Return:** Default `1` (returns single object). If `> 1`, returns a list. |
### B. Cascading Logic (Specificity)
The API automatically resolves the "best fit" record in the following order:
1. **Record Specific:** Matches `for_type` + `for_id` (and account).
2. **Account Specific:** Matches the `x-account-id` header.
3. **Global Default:** Matches `code` where `account_id` is `NULL`.
### B. Cascading Logic (The Hierarchy of Truth)
The API automatically resolves the most specific record available using the following priority:
**Object Override > Account Override > Global System Default.**
### C. Example Implementation
| Specificity | `account_id` | `for_type` | `for_id` | `code` | `Result` |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Global** | `NULL` | `NULL` | `NULL` | `'site_config'` | System default (blue theme). |
| **Account** | `'abc123_rd'` | `NULL` | `NULL` | `'site_config'` | Acme Corp default (green theme). |
| **Object** | `'abc123_rd'` | `'event'` | `'evt_xyz_rd'` | `'site_config'` | Main Conference override (gold theme). |
### C. Rules for Frontend Agents
1. **Vision IDs Only:** Always use random string IDs (e.g., `evt_xyz_rd`) for `for_id`. Never use database integers.
2. **Explicit Context:** If you are within an Event or Person context, always provide `for_type` and `for_id`. The API will handle the fallback if a specific record doesn't exist.
3. **Automatic JSON Parsing:** If the record `type` is `'json'`, the API returns a structured object/list under the `json` key. You do not need to call `JSON.parse()`.
4. **Handling the Return:**
* `limit=1` (Default): Returns a single **Object** in `data`.
* `limit>1`: Returns a **List** of objects in `data`.
### D. Example Implementation
```ts
// GET /v3/data_store/code/event_launcher_main_info?for_type=event&for_id=nmBfuGFeR0k&limit=1
export async function get_data_store_v3({ api_cfg, code, for_type, for_id, limit = 1 }) {
@@ -169,3 +181,4 @@ export async function get_data_store_v3({ api_cfg, code, for_type, for_id, limit
return await get_object({ api_cfg, endpoint, params });
}
```