diff --git a/documentation/GUIDE__V3_FRONTEND_API.md b/documentation/GUIDE__V3_FRONTEND_API.md index 562a84a..cf09dac 100644 --- a/documentation/GUIDE__V3_FRONTEND_API.md +++ b/documentation/GUIDE__V3_FRONTEND_API.md @@ -1,6 +1,6 @@ # Aether API V3 Frontend Integration Guide (Svelte/TypeScript) -This guide defines the standards for interacting with the **Aether API V3 CRUD** and **Action** endpoints. +This guide defines the standards for interacting with the **Aether API V3 CRUD** and **Action** endpoints. --- @@ -16,7 +16,7 @@ V3 architecture enforces strict **Multi-Tenant Isolation** and **Machine Authori ### B. The "Visa" (Account Context) Required for any non-public data (Journals, Badges, Users, etc.). 1. **Standard Access**: Provide the `x-account-id` (the random string ID). - * **Header:** `x-account-id: ` + * **Header:** `x-account-id: ` 2. **Administrative Bypass**: For authorized scripts needing global access. * **Header:** `x-no-account-id: bypass` 3. **Token Access**: Provide a **JWT** in the query string. @@ -41,8 +41,8 @@ When the frontend first loads and doesn't know the `account_id`, it performs a " } ``` **Results:** -* Returns 200 + a list containing the `account_id` and `site_id` random strings. -* ** ڈیزائن Choice:** If the domain is not found, it returns **200 OK with an empty list `[]`**. It is NOT a 404. +* Returns 200 + a list containing the `account_id` (random string ID) and `site_id` (random string ID). +* ** デザイン Choice:** If the domain is not found, it returns **200 OK with an empty list `[]`**. It is NOT a 404. --- @@ -50,7 +50,7 @@ When the frontend first loads and doesn't know the `account_id`, it performs a " ### A. GET by ID Used when the ID is known. -* **Endpoint:** `GET /v3/crud/{obj_type}/{id_random}` +* **Endpoint:** `GET /v3/crud/{obj_type}/{id}` * **Security:** Returns 403 if the record doesn't belong to your `x-account-id`. ### B. POST Search @@ -62,11 +62,11 @@ The primary way to retrieve data. ## 4. Event File Data Retrieval (Hosted Files) -Event Files (`event_file`) often have associated Hosted Files (`hosted_file`) which contain binary data and metadata like SHA256 hashes, content types, and sizes. To retrieve this additional data: +Every Event File (`event_file`) **must** have a linked Hosted File (`hosted_file`). The Hosted File itself is a metadata record for binary content (files), which is accessed via separate Action endpoints (e.g., `/v3/action/hosted_file/download`). This API endpoint provides metadata about the associated hosted file. To retrieve this additional metadata: -* **Endpoint:** `GET /v3/crud/event_file/{event_file_id_random}` +* **Endpoint:** `GET /v3/crud/event_file/{event_file_id}` * **Query Parameter:** Add `inc_hosted_file=true` - * Example: `/v3/crud/event_file/?inc_hosted_file=true` + * Example: `/v3/crud/event_file/?inc_hosted_file=true` **Response Impact:** @@ -86,4 +86,3 @@ If you receive a 403 on a valid ID: 2. Ensure you are sending `x-account-id` and NOT `x-aether-api-token`. 3. Verify the record actually belongs to the account ID you are sending. 4. Check if the object is marked `public_read: True` in the registry. (Posts and Archive Content allow guest access; Journals and Badges do not). -