OSIT-AE-API-FastAPI/documentation/GUIDE__V3_FRONTEND_API.md

Aether API V3 Frontend Integration Guide (Svelte/TypeScript)

This guide explains how to update or create frontend functions to interact with the new Aether API V3 CRUD and Action endpoints. V3 introduces a nested URL structure, a powerful POST-based search, and specialized "Action" routes for binary data.

---

1. Key Differences (V2 vs V3)

Feature	CRUD V2 (Legacy)	CRUD V3 (Modern)
Base Prefix	/v2/crud	/v3/crud
List Suffix	Uses /list	No suffix (e.g., /v3/crud/journal/)
Nested Path	Not supported in URL	Supported (e.g., /v3/crud/journal/{id}/entry/)
View Selection	tbl_alt, mdl_alt	view parameter (e.g., ?view=enriched)
Complex Search	Limited to GET jp	POST /search (Unlimited size + Hybrid params)
Full-Text	Manual column names	Reserved q property in SearchQuery

---

2. Authentication and Security (Mandatory)

As of January 2026, the V3 architecture enforces strict Multi-Tenant Isolation and Machine Authorization. Most requests require two levels of validation.

A. The "Entry Ticket" (API Key)

Mandatory for all requests. Every request must provide a valid x-aether-api-key in the header. This identifies the application or script.

• Header: x-aether-api-key: <your_app_key>
• Status Code: 403 Forbidden if missing, invalid, or expired.

B. The "Visa" (Account Context)

Once the API Key is validated, you must specify the context of your request.

1. Standard User Access: Provide the x-account-id (the random string ID).
   • Header: x-account-id: <account_id_random>
2. Administrative Bypass: For authorized scripts needing global access.
   • Header: x-no-account-id: bypass
3. Guest / Anonymous Access: Provide a Safe Guest JWT.
   • Header: x-aether-api-key: <your_app_key> (No Account Header)
   • Query Param: ?jwt=<guest_token>

---

3. Implementing V3 CRUD Functions

A. List & Single Object (GET)

// GET /v3/crud/journal/{id}?view=enriched
export async function get_ae_obj_v3({ api_cfg, obj_type, obj_id, view = 'default' }) {
    const endpoint = `/v3/crud/${obj_type}/${obj_id}`;
    return await get_object({ api_cfg, endpoint, params: { view } });
}

B. Advanced & Hybrid Search (POST)

// POST /v3/crud/{obj_type}/search
export async function search_ae_obj_v3({ api_cfg, obj_type, search_query, enabled = 'enabled' }) {
    const endpoint = `/v3/crud/${obj_type}/search`;
    return await post_object({ api_cfg, endpoint, params: { enabled }, data: search_query });
}

---

4. Hosted File Management (Modern V3 Actions)

V3 uses specialized "Action" routes for binary operations to separate processing logic from standard metadata CRUD.

A. Upload Action

Path: POST /v3/action/hosted_file/upload Format: multipart/form-data

Field	Type	Required	Description
file_list	File[]	Yes	One or more files to upload.
account_id	String	Yes	Random ID of the owner account.
link_to_type	String	Yes	Object type to link (e.g., archive_content).
link_to_id	String	Yes	Random ID of the object to link.

Query Parameters:

• allowed_extensions: Whitelist check (e.g., ?allowed_extensions=png&allowed_extensions=jpg).
• delay_ms: Simulate network delay for UI testing.

Features:

• Automatic Deduplication: API checks SHA256 hashes. If a file exists on the server, it reuses the record and creates a new link instead of a duplicate upload.
• Relational Integrity: Automatically creates hosted_file_link records.

B. Download & Streaming Action

Path: GET /v3/action/hosted_file/{id}/download

Features:

• ID Vision: Automatically resolves {id} if it belongs to a container object (e.g., event_file) instead of a direct hosted_file.
• Streaming: Supports standard Range headers for large files and video seeking.
• Auth Bypass: Use ?site_key=<auth_key> to download without an API Key header or JWT (useful for public kiosks).
• Testing: Supports delay_ms query parameter.

C. Deletion & Cleanup Action

Path: DELETE /v3/action/hosted_file/{id}

Parameter	Type	Default	Description
link_to_type	Query	null	The type of the link to remove.
link_to_id	Query	null	The random ID of the link to remove.
rm_orphan	Query	false	If true, physically delete file if no links remain.
method	Query	hide	Cleanup method: hide, disable, or delete (hard).
fake_delete	Query	false	Testing Mode: Verifies file/record existence without modification.

---

5. Hosted File Management (Legacy)

The following endpoints are maintained for backward compatibility but should be migrated to V3 Actions.

Method	Endpoint	Description
POST	/hosted_file/upload_files	Legacy multi-upload.
GET	/hosted_file/{id}/download	Legacy download.
GET	/hosted_file/{id}/stream	Legacy buffered streamer.
DELETE	/hosted_file/{id}	Legacy deletion.

---

6. The "ID Vision" Standard (2026)

V3 uses a String-Only ID Vision. The frontend NEVER handles or stores database integers.

1. Automatic Mapping: Internal id_random fields are mapped to id and account_id in JSON responses.
2. Intelligent Resolution: You can send random string IDs back to the API in any *_id field; the API resolves them to integers before database insertion.

---

9. Real-Time Communication (V3 WebSockets)

V3 WebSockets provide a granular, high-performance messaging layer.

• Guide: Aether API V3 WebSocket Integration Guide
• Endpoint: ws://[api_domain]/v3/ws/group/{group_id}/client/{client_id}
• Key Requirement: All messages must conform to the WS_Message_V3 schema.

---

10. Structured Error Handling

V3 returns machine-readable error objects in meta.details for failures.

HTTP Status Codes

• 400 Bad Request: Used for client-driven errors including invalid search fields, validation failures, and constraint violations.
• 403 Forbidden: Missing or invalid API Key / Account Context.
• 404 Not Found: Object ID does not exist.
• 500 Internal Server Error: Unexpected server crash or database connection failure.

Common Error Categories

Found in meta.details.category:

• database_duplicate: Non-unique value (Code 1062). -> 400
• database_constraint: Foreign key violation (Codes 1451, 1452). -> 400
• database_schema: Invalid column name or missing field in the requested view (Codes 1054, 1146). -> 400
• validation: Pydantic validation failed (Check details for field-specific errors). -> 400

---

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" record for the current user and object context.

A. The V3 Lookup Endpoint

Path: GET /v3/data_store/code/{code}

Query Parameters:

Parameter	Type	Required	Description
for_type	String	No	Parent object type (e.g., event, person).
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 (The Hierarchy of Truth)

The API automatically resolves the most specific record available using the following priority: Object Override > Account Override > Global System Default.

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

// 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 }) {
    const endpoint = `/v3/data_store/code/${code}`;
    const params = { for_type, for_id, limit };
    return await get_object({ api_cfg, endpoint, params });
}